{"openapi":"3.0.3","info":{"title":"Autario Data API","version":"1.0.0","description":"Structured dataset discovery and querying API for humans and AI agents.\n\n## Authentication\nPrivate endpoints require two headers:\n- `x-api-key`: Your API key (visible in Account > API Keys)\n- `x-api-secret`: Your API secret (shown once at key creation)\n\n## Rate Limits\nTwo separate 120 req/min per IP budgets, each reported on its own responses via\n`X-RateLimit-Limit` / `-Remaining` / `-Reset` (CORS-exposed, readable from JS):\n- **data**: the `/api/v1/public/*` GETs. Skipped entirely for authenticated callers.\n- **docs**: `/api/v1`, `/api/v1/guide`, `/api/v1/openapi.json`, `/api/v1/apps/quickstart`,\n  `/api/v1/autario.js`. Reading the documentation does NOT spend the data budget.\n  These files are static; cache them rather than re-fetching.\n\n## Request Tracing\nEvery response includes an `X-Request-ID` header (UUID v4) that uniquely\nidentifies the request in server logs. Include this ID when reporting bugs.\nClients may also send `X-Request-ID` on inbound requests (up to 64 chars)\nto propagate an existing trace chain.\n\n## Filter Syntax\nUse the `filter` query parameter with format `column:op:value` (public /data endpoints and the proxy `datasetData` op).\nOperators: `eq` (=), `neq` (<>), `gt` (>), `lt` (<), `gte` (>=), `lte` (<=), `like` (ILIKE, auto-wrapped in %).\nRepeat the parameter for multiple conditions: `?filter=year:gt:2020&filter=country:eq:Germany`\nException: the private `/datasets/{id}/query` endpoint takes `filters` (plural).\n\n## Unknown query params\nAn unknown query param is IGNORED, never guessed, and the public read endpoints say so: the response carries an additive `query_diagnostics` block naming `unknown_params` and `accepted_params`.\nIf you sent `?search=` where the endpoint reads `?q=`, that block is how you find out, instead of mistaking a full collection for a hit."},"servers":[{"url":"https://autario.com/api/v1","description":"Production"}],"components":{"parameters":{"StatsEntity":{"name":"entity","in":"query","required":true,"schema":{"type":"string","example":"DEU"},"description":"Entity code or name: ISO-3 country code (DEU, USA), aggregate (EUU, WLD), or a canonical name."},"StatsIndicator":{"name":"indicator","in":"query","required":true,"schema":{"type":"string"},"description":"Indicator id from the ontology (discover via MCP list_indicators or get_entity_profile). Raw provider codes like NY.GDP.MKTP.CD are NOT ids."},"StatsTime":{"name":"time","in":"query","required":false,"schema":{"type":"string","example":"2010-2023"},"description":"Optional time range (YYYY-YYYY) or single period (YYYY)."},"StatsFull":{"name":"full","in":"query","required":false,"schema":{"type":"boolean"},"description":"Also return the per-timepoint array (token-heavy). Default: summary + interpretation only."}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key from Account > API Keys"},"ApiSecretAuth":{"type":"apiKey","in":"header","name":"x-api-secret","description":"Your API secret (shown only once at key creation)"}},"responses":{"PlanLimit":{"description":"Payment required. The request was well-formed and authenticated, and a limit stopped it. Branch on `reason`: `plan_limit` (a ceiling is full), `plan_required` (the action is not part of this tier), `allowance_exhausted` (a refilling meter is spent) or `keys_required` (the caller must add their own vendor key, and nothing is for sale). One field vocabulary across all four, so a client that reads `reason`, `current_plan`, `required_plan`, `price` and `upgrade_url` renders every one of them. `current_plan` is always read from the database at call time, never from a token. Do not retry on a timer: nothing changes inside the window on its own.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLimitError"}}}}},"schemas":{"DatasetReferences":{"type":"object","description":"The dataset ids a bundle references: written as string literals in a bundle that calls autario.js. Deduplicated, lowercase.","properties":{"datasets":{"type":"array","items":{"type":"string","format":"uuid"}},"count":{"type":"integer"}}},"PlanLimitError":{"type":"object","required":["error","reason","current_plan"],"properties":{"error":{"type":"string","description":"One honest English sentence, already carrying the numbers. For a human. Never parse it."},"reason":{"type":"string","enum":["plan_limit","plan_required","allowance_exhausted","keys_required"],"description":"Which refusal this is, and the one field to branch on. plan_limit: a ceiling is full. plan_required: the action is not in this tier at all. allowance_exhausted: a refilling meter is spent. keys_required: bring your own key, nothing is for sale."},"scope":{"type":"string","enum":["private_apps","storage_mb","api_calls_day","connector_accounts","share_link","visibility_checks","reader_seats","prefill","app_datasets"],"description":"plan_limit, and allowance_exhausted where a named meter refused: WHICH ceiling. A closed set, so a client can group a user's limits without parsing prose."},"limit_kind":{"type":"string","enum":["total","per_connector"],"description":"Only where one scope has two shapes: connected accounts are capped in total on the free tier and per connector on the paid ones."},"feature":{"type":"string","description":"plan_required, allowance_exhausted and keys_required: the blocked action, next to scope which names the meter. A run is refused as feature visibility_run against scope visibility_checks."},"unit":{"type":"string","description":"The noun the numbers count, in the caller's own words, for example checks or AI drafts."},"used":{"type":"integer","description":"How much of the meter is spent."},"limit":{"type":"integer","description":"The ceiling that was hit."},"remaining":{"type":"integer","description":"What is left. Already the subtraction the sentence did, so a client never repeats it."},"requested":{"type":"integer","description":"allowance_exhausted: the size of the refused action, which is what makes the message honest when one action is simply bigger than the remainder."},"resets_at":{"type":"string","format":"date-time","nullable":true,"description":"When the meter refills. Null means it does not come back by waiting, which is the difference between a monthly quota and a one-off trial."},"window":{"type":"string","enum":["month","trial"],"description":"allowance_exhausted: which meter refused."},"current_plan":{"type":"string","description":"The tier the account actually holds, read from the database at call time and never from a token."},"required_plan":{"type":"string","description":"The tier that lifts this refusal. Absent on keys_required, where nothing is for sale."},"price":{"type":"number","description":"Monthly price of required_plan in the catalog currency. Absent on keys_required."},"upgrade_url":{"type":"string","description":"Where to send a person. Absent on keys_required."},"missing_vendors":{"type":"array","description":"keys_required: the vendors the caller holds no key for.","items":{"type":"object","properties":{"vendor":{"type":"string"},"label":{"type":"string"},"assistant":{"type":"string"},"dashboard_url":{"type":"string","description":"Where that vendor issues a key."}}}},"settings_url":{"type":"string","description":"keys_required: where a key goes."}}},"DatasetLineage":{"type":"object","nullable":true,"description":"Where this private or derived table comes from and what reads it, at table level and read-only. Absent on public catalog datasets. Built from relations that already exist (connector instance -> report table, the metric layer fold, app result tables, app manifests, charts, Projects KPIs, the dataset share). null when it could not be read.","properties":{"viewer":{"type":"string","enum":["owner","team","reader"],"description":"The cut you got: owner = everything; team = a team reader of an app result table (upstream + apps); reader = the table was shared with you (kind of each source, nothing downstream)."},"upstream":{"type":"array","items":{"$ref":"#/components/schemas/LineageNode"},"description":"Where it comes from: connector (instance + report), upload, app_result (app + brand), dataset (a table folded into this derived one; its connector one level deeper)."},"downstream":{"type":"array","items":{"$ref":"#/components/schemas/LineageNode"},"description":"What reads it: derived (a table it feeds), app, chart, kpi, share. An app that reads it through a derived table sits at depth 2 under that table."},"counts":{"type":"object","properties":{"upstream":{"type":"integer"},"downstream":{"type":"integer"},"by_kind":{"type":"object","additionalProperties":{"type":"integer"}}}},"upstream_empty":{"type":"string","nullable":true,"description":"One sentence when upstream is empty, else null."},"downstream_empty":{"type":"string","nullable":true,"description":"One sentence when downstream is empty, else null."},"accepted_overlays":{"type":"integer","nullable":true,"description":"Accepted overlay entries on this table (owner only, else null). The overlay layer itself is GET /datasets/{id}/overlays."},"last_structure_change":{"allOf":[{"$ref":"#/components/schemas/DatasetChangelogEntry"}],"nullable":true}}},"LineageNode":{"type":"object","properties":{"kind":{"type":"string","enum":["connector","upload","app_result","dataset","derived","app","chart","kpi","share"]},"id":{"type":"string"},"label":{"type":"string"},"detail":{"type":"string","nullable":true},"href":{"type":"string","nullable":true,"description":"The autario page of the node, relative. null where the caller may not open it."},"depth":{"type":"integer","minimum":1,"maximum":2}}},"DatasetMeta":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"publisher":{"type":"string","description":"Dataset owner or copyright holder"},"rows":{"type":"integer","nullable":true},"is_owner":{"type":"boolean","description":"True if the authenticated user owns this dataset"},"created_at":{"type":"string","format":"date-time"},"last_refreshed_at":{"type":"string","format":"date-time","nullable":true,"description":"INGEST FRESHNESS: when autario last pulled this source and wrote rows. null when it was never re-ingested. This is a DIFFERENT fact from the newest data point (which lives on the dataset's time axis, see /schema): last_refreshed_at answers \"how recently did you check\", the time axis answers \"how new is the newest value\". A source that quietly stopped publishing keeps a fresh last_refreshed_at and an old newest value, which is exactly the case you cannot detect from the data alone. Caveat: a source that answers 304 Not Modified is skipped without a write, so this stamp can lag the last CHECK by a refresh cycle. It never runs ahead of the data."},"dataset_url":{"type":"string","nullable":true,"description":"THE CITABLE PAGE for this dataset: https://autario.com/data/<slug>. Put this in a citation. It is the canonical form and always uses the slug (a /data/<uuid> URL does not resolve); /dataset/<slug> and /datastore/<slug> both 301 here."},"schema_version":{"type":"integer","description":"Structural version of this dataset's table. Starts at 1 and is bumped every time a column is renamed, dropped or retyped, or the unit changes. Poll it (or the changelog endpoint) if your code maps our field names into your own: a value higher than the one you last saw means the shape moved. NOT the same as the dataset's data freshness (last_refreshed_at) and not the version of any LLM judgement."},"changelog":{"type":"array","description":"The last 5 structural changes of this dataset, newest first. Empty when nothing was recorded. Full history at GET /public/datasets/{id}/changelog.","items":{"$ref":"#/components/schemas/DatasetChangelogEntry"}},"lineage":{"$ref":"#/components/schemas/DatasetLineage"},"is_discontinued":{"type":"boolean","description":"True when the original source stopped responding. The dataset stays fully readable (values = last good snapshot) but is excluded from listings/search."},"discontinued_at":{"type":"string","format":"date-time","nullable":true,"description":"When the source was marked discontinued"},"discontinued_reason":{"type":"string","nullable":true,"description":"Why the source was marked discontinued"},"splits":{"type":"array","description":"Stock split timeline (stock price datasets); [] for non-stock. Each entry is a real split event, ascending by date.","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Split effective date (YYYY-MM-DD)"},"ratio":{"type":"number","description":"Post-split shares per pre-split share (a 7:1 split = 7)"}}}}}},"DatasetChangelogEntry":{"type":"object","description":"One recorded structural change of a dataset. A value refresh (same columns, new rows) is deliberately NOT recorded.","properties":{"detected_at":{"type":"string","format":"date-time","description":"When the engine detected the change"},"date":{"type":"string","format":"date","description":"detected_at as a plain UTC date, the form the dataset page prints"},"kind":{"type":"string","enum":["breaking","rename","additive","semantic","oscillating"],"description":"breaking = a column vanished or changed type. rename = a vanished column has a high-confidence successor. additive = only new columns, existing field names untouched. semantic = the columns are unchanged but the unit or value kind moved, so every stored number now means something else. oscillating = columns already on record as removed come and go from run to run; the table keeps every column (empty where a run did not deliver it), never bumps the version, and is listed once."},"schema_version":{"type":"integer","description":"The version the dataset stands at AFTER this change. additive does not bump it."},"source":{"type":"string","enum":["provider","engine"],"description":"provider = the upstream payload changed shape. engine = our own parser or indicator registry changed it (for example a unit correction)."},"diff":{"type":"object","description":"What moved: {added[], removed[], renamed{from:to}, type_changed[{column,from,to}], unit{from,to}, value_kind{from,to}}. Only the non-empty members are present. The OLD column set exists nowhere else after the table was rebuilt."},"summary":{"type":"string","description":"The change as one plain-English sentence, identical to the one printed on the dataset page."},"consequence":{"type":"string","description":"What a consumer should do about it, one short line."}}},"ColumnInfo":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","example":"text","description":"PostgreSQL data type"},"nullable":{"type":"boolean"},"position":{"type":"integer"}}},"ConnectorInstance":{"type":"object","properties":{"id":{"type":"string","description":"Connector instance id (use for refresh / detail)"},"name":{"type":"string"},"status":{"type":"string","enum":["active","running","error"]},"refresh_interval_minutes":{"type":"integer","description":"0 = manual only"},"last_run_at":{"type":"string","format":"date-time","nullable":true},"last_error_message":{"type":"string","nullable":true},"output_table_name":{"type":"string","nullable":true},"dataset_id":{"type":"string","format":"uuid","nullable":true,"description":"Dataset id of the primary hosted table; pass to getDatasetSchema / queryDataset"},"row_count":{"type":"integer","nullable":true},"datasets":{"type":"array","description":"Every dataset this instance materialized (multi-report connectors produce one per report); [] before the first run","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"slug":{"type":"string","nullable":true},"rows":{"type":"integer","nullable":true}}}},"health":{"nullable":true,"description":"Compact health on listConnectors (state, sentence, last_run_at, data_as_of, next_step); the full ConnectorHealth on getConnector and refreshConnector. null when it could not be read. Spec 2026-10-05-mcp-connector-health.","allOf":[{"$ref":"#/components/schemas/ConnectorHealth"}]}}},"ConnectorHealth":{"type":"object","description":"Can the caller trust this connector's numbers, and who has to act. Built from the same per-report fold the setup page shows and the same alert decision the notification bell uses.","properties":{"state":{"type":"string","enum":["ok","stale","needs_sign_in","reports_missing","retrying","ours","never_ran","running"],"description":"stale = a scheduled instance not pulled for min(2 x its interval, 48 h); manual-only instances are never stale. needs_sign_in = the login is gone, only the user can fix it. ours = a problem on autario's side. retrying = the provider had a temporary problem."},"sentence":{"type":"string"},"last_run_at":{"type":"string","format":"date-time","nullable":true},"last_success_at":{"type":"string","format":"date-time","nullable":true,"description":"Full view only"},"schedule":{"type":"string","example":"every day","description":"Full view only; 'manual only' when the instance has no schedule"},"next_run_at":{"type":"string","format":"date-time","nullable":true,"description":"Full view only; null for manual only"},"data_as_of":{"type":"array","items":{"type":"object","properties":{"dataset_id":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"as_of":{"type":"string","format":"date","nullable":true},"basis":{"type":"string","enum":["data_day","last_pulled"],"description":"data_day = newest day inside the table (full view, when the table has a time column); last_pulled = when it was fetched"}}}},"reports":{"type":"array","description":"Full view only: one entry per active report of the last run. An empty report is not a problem: the account has no such data.","items":{"type":"object","properties":{"report":{"type":"string"},"name":{"type":"string"},"outcome":{"type":"string","enum":["delivered","empty","not_fetched"]},"rows":{"type":"integer","nullable":true},"sentence":{"type":"string"}}}},"next_step":{"type":"object","properties":{"who":{"type":"string","enum":["assistant","user","nobody"]},"action":{"type":"string"},"url":{"type":"string","nullable":true,"description":"The setup page where the user acts (sign in again, fix a field)"}}}}},"IncompatibleSemantics":{"type":"object","description":"The refusal a caller gets when it asks autario to combine two columns that describe different facts (spec 2026-09-21-column-semantics). It is machine-readable on purpose: `allowed` tells the caller what to do instead.","properties":{"error_code":{"type":"string","example":"incompatible_semantics"},"error":{"type":"string","description":"One sentence a model can act on.","example":"sessions (sessions) and clicks (clicks) are different kinds of number. Compare them side by side instead."},"reason_code":{"type":"string","enum":["different_kind","different_unit","different_currency","different_grain","rate_not_additive","not_a_known_rate","not_a_known_product","not_a_measure","override_without_reason"]},"op":{"type":"string"},"left":{"type":"object","description":"The left column: indicator, dataset title and its resolved semantics."},"right":{"type":"object","description":"The right column, same shape."},"allowed":{"type":"array","description":"The operations this pair DOES support, with the kind each would produce. Empty when the two facts simply do not belong together.","items":{"type":"object","properties":{"op":{"type":"string"},"result_kind":{"type":"string","nullable":true}}}},"override_hint":{"type":"string"}}},"SchemaResponse":{"type":"object","properties":{"dataset_id":{"type":"string","format":"uuid"},"row_count":{"type":"integer"},"column_count":{"type":"integer"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/ColumnInfo"}},"semantics":{"type":"object","description":"What each column MEANS, keyed by column name. `kind` is one of a closed vocabulary (impressions, clicks, sessions, users, conversions, orders, followers, views, engagements, spend, revenue, conversion_value, ctr, cpc, cpa, roas, engagement_rate, plus the identifier and time kinds); `source` says where the meaning came from: `registry` (the connector operation is declared in the metric registry, or this is the derived marketing table), `column_name` (the column name is a declared alias), `asset` (a catalog dataset whose unit is declared) or `none` (nothing is known, which is honest and refuses nothing). Shadow columns (autario_*) carry no entry. Combining two columns of different kinds is refused by the stats endpoints.","additionalProperties":{"type":"object","properties":{"column":{"type":"string"},"kind":{"type":"string","nullable":true,"example":"clicks"},"class":{"type":"string","nullable":true,"enum":["count","money","rate","identifier","time",null],"description":"Which family the kind belongs to."},"measure":{"type":"string","nullable":true,"enum":["flow","level","ratio","none",null],"description":"flow accumulates over the window, level is a state at a point in time."},"unit":{"type":"string","nullable":true,"example":"current us$"},"currency":{"type":"string","nullable":true},"grain":{"type":"string","nullable":true,"example":"day","description":"The time grain of the observation (day, week, month, quarter, year)."},"definition":{"type":"string","nullable":true,"description":"One line saying what the column counts or measures."},"formula":{"type":"string","nullable":true,"description":"For a rate kind, the division it is."},"reported_by":{"type":"string","nullable":true,"description":"The channel that reported the number, under its own definition."},"sentence":{"type":"string","description":"The whole thing as one plain sentence, ready to read."},"source":{"type":"string","enum":["registry","column_name","asset","none"]}}}},"semantics_rule":{"type":"string","description":"The combination rule in one sentence, so a client that only reads this response still learns it."},"lineage":{"$ref":"#/components/schemas/DatasetLineage"},"source_time_col":{"type":"string","nullable":true,"description":"THE time axis of this dataset: the column every time-aware surface reads, and the column the `endpoints` dates in summary_only are taken from. Read it before interpreting such a date. On a dataset that carries an explicit reporting period (start + end plus a period label) this is deterministically `end`, the period CLOSE, for every dataset of that shape."},"source_entity_col":{"type":"string","nullable":true,"description":"THE entity axis (which column names the thing each row is about)."},"source_value_col":{"type":"string","nullable":true,"description":"THE measured column (the one autario_value mirrors)."},"column_roles":{"type":"object","description":"Per role, the default column plus any alternates the detector also considered. `time.default.col` is the same column as source_time_col; `alternates` exist when a dataset has more than one time-shaped column and a client may offer a switch. confidence 1 means the column was declared at ingest rather than detected. An empty object means no role was recorded and no axis column is declared either.","properties":{"time":{"type":"object","properties":{"default":{"type":"object","properties":{"col":{"type":"string","example":"end"},"confidence":{"type":"number","example":1},"shadow":{"type":"string","example":"autario_time","description":"The normalized companion column holding this axis in ISO form"}}},"alternates":{"type":"array","items":{"type":"object"}}}}}}}},"QueryMeta":{"type":"object","properties":{"total":{"type":"integer","description":"Total matching rows (ignoring pagination)"},"returned":{"type":"integer","description":"Rows in this response"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"QueryResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/QueryMeta"},"data":{"type":"array","items":{"type":"object","properties":{"dd_id":{"type":"integer","description":"Row number autario assigns when the row is written; the default order of this endpoint is dd_id descending, newest first. It identifies a row only until the table is replaced: a connector refresh that rewrites the whole table, or DELETE /datasets/{id}/rows followed by a new write, can give the same row a different number."}},"additionalProperties":true}}}},"QueryDiagnostics":{"type":"object","description":"Present ONLY when the query matched 0 rows, part of the request was ignored, or the returned rows are not a continuous period series. Absent on a clean, non-empty, continuous result, so existing clients are unaffected.","required":["reason","filters_applied","filters_ignored","unknown_params"],"properties":{"reason":{"type":"string","enum":["no_rows_matched","params_ignored","period_gaps"],"description":"The primary problem, most blocking first. no_rows_matched when the query returned nothing; params_ignored when it returned rows but something in the request was dropped; period_gaps when the request was clean and the rows themselves have a hole. period_gaps is reported whenever it applies, independent of which reason won."},"period_gaps":{"type":"array","description":"Holes between the periods of the rows THIS response returns. Present only when there is at least one. This is the only field here that describes a query asked CORRECTLY: summing four rows from a series with a hole (the documented TTM recipe) reports a longer span than twelve months. Each entry names the period end a caller would have summed straight past. Computed only for row pages that carry period columns (start/end, or end plus period_months) and are small enough to be a summing window.","items":{"type":"object","properties":{"after":{"type":"string","example":"2025-09-30","description":"End of the period BEFORE the hole"},"next_start":{"type":"string","example":"2026-01-01","description":"Start of the next period present"},"missing_months":{"type":"integer","example":3,"description":"Measured width of the hole in months, rounded, never below 1"}}}},"filters_applied":{"type":"array","description":"Filters that resolved and ran. matched_rows is filled in only for a zero-row result (how many rows that filter alone matches).","items":{"type":"object","properties":{"raw":{"type":"string","example":"cq:eq:Y"},"column":{"type":"string","example":"cq"},"op":{"type":"string","example":"eq"},"value":{"type":"string","example":"Y"},"matched_rows":{"type":"integer","nullable":true}}}},"filters_ignored":{"type":"array","description":"Parts of the request that did not resolve against this dataset and were silently dropped before this block existed.","items":{"type":"object","properties":{"param":{"type":"string","enum":["filter","fields","sort","groupby","aggregate"]},"raw":{"type":"string"},"reason":{"type":"string","enum":["unknown_column","unknown_operator","unknown_column_or_function","malformed"]},"column":{"type":"string","description":"Present when the reason names a column"},"op":{"type":"string","description":"Present for unknown_operator"}}}},"unknown_params":{"type":"array","description":"Query keys this endpoint does not understand, sorted. A typo shows up here instead of being ignored in silence.","items":{"type":"string"}},"accepted_params":{"type":"array","description":"The full accepted param list. Only present when unknown_params is non-empty.","items":{"type":"string"}},"rows_without_filters":{"type":"integer","description":"Rows the dataset holds with no filter applied. Only present when it could be counted."},"column_values_sample":{"type":"object","description":"Up to 5 real DISTINCT values for up to 2 columns whose filter matched nothing, so the caller sees what the column actually contains.","additionalProperties":{"type":"array","items":{}},"example":{"cq":["Q1","Q2","Q3","Q4"]}},"hint":{"type":"string","description":"Deterministic one-line explanation naming the culprit filter or the ignored params.","example":"Filter cq:eq:Y matched 0 of 72 rows on its own. Values present in column cq: Q1, Q2, Q3, Q4."}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}},"DatasetNotFound":{"type":"object","description":"The 404 every /public/datasets/* read returns when the id or slug resolves to no dataset the caller may see. Same error_code + hint contract as unknown_endpoint and unknown_ticker, so an agent can branch on the code and never parse prose. Additive: `error` keeps its historical value \"Dataset not found\".","properties":{"error":{"type":"string","example":"Dataset not found"},"error_code":{"type":"string","enum":["unknown_dataset"],"description":"Always unknown_dataset. Both id forms (UUID and slug) are accepted on every path, so this code means the DATASET is unknown, never that the identifier form was wrong."},"requested":{"type":"string","nullable":true,"description":"The id or slug you sent, echoed back (capped at 200 chars) so a batch caller sees WHICH lookup failed. Absent when the request carried no id."},"hint":{"type":"string","description":"The next call that fixes it: search the catalog with GET /public/datasets?q=<term>, or resolve a company ticker with GET /public/markets/{ticker}/datasets."}}},"PublicAuthRefusal":{"type":"object","description":"The 401 the two authenticated endpoints under /public/* return to an anonymous caller (GET /public/datasets/{id}/export, POST /public/ingest/ticker). Same error_code + hint contract as unknown_dataset / unknown_endpoint / unknown_ticker: branch on the code, never parse the prose. The hint names the headers this API actually accepts (x-api-key + x-api-secret) and the credential-free call that answers a neighbouring question. Additive: `error` keeps its historical value.","properties":{"error":{"type":"string","example":"Login required to download data"},"error_code":{"type":"string","enum":["login_required","api_key_required"],"description":"login_required on the bulk download wall, api_key_required on the on-demand ingest write."},"hint":{"type":"string","description":"How to authenticate (x-api-key + x-api-secret from Account > API Keys) plus the credential-free endpoint that answers a neighbouring question."}}},"AppAuthRefusal":{"type":"object","description":"The 401/403 the app endpoints under /public/apps/* return. Same error_code contract as PublicAuthRefusal (branch on the code, never parse the prose), one code more: not_owner. Additive, `error` keeps its historical value. An app in private preview answers 403 with error_code 'app_in_draft' instead.","properties":{"error":{"type":"string","example":"You do not own this app."},"error_code":{"type":"string","enum":["login_required","not_owner"],"description":"login_required when no identity was sent; not_owner when the app exists but belongs to another account. not_owner is deliberately not a generic 'forbidden': it tells you that other credentials will NOT help, so register your own app id instead of retrying."},"hint":{"type":"string","description":"For login_required: how to authenticate (x-api-key + x-api-secret from Account > API Keys). For not_owner: the door you do own, POST /public/apps/{your-app-id}/manifest."}}},"ProxyError":{"type":"object","description":"Proxy/error envelope: a machine-readable code plus a human message. Never echoes the token.","properties":{"error_code":{"type":"string","example":"op_not_in_scope"},"error":{"type":"string"},"valid_ops":{"type":"array","items":{"type":"string"},"description":"Present on bad_op / bad_scope errors"}}},"StatsResponse":{"type":"object","description":"Stats result: the computed statistic(s), the covered time_range/n, and a human-readable interpretation block. Summary by default; pass full=true (or include_series=true) for the per-timepoint array (token-heavy)."},"AppManifest":{"type":"object","description":"An app's submission manifest projection (the `apps` row).","properties":{"id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"integer","enum":[1,2],"description":"1 = declarative, 2 = sandboxed"},"owner_id":{"type":"string","nullable":true},"consumed_datasets":{"type":"array","items":{"type":"string"}},"entry_url":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"source_url":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","submitted","approved","published"]},"route":{"type":"string","nullable":true},"tagline":{"type":"string","nullable":true,"description":"One-line description. Writable through the manifest door since 2026-08-30 (trimmed, max 200 chars)."},"publisher":{"type":"string","nullable":true},"category":{"type":"string","nullable":true,"description":"The app's SHELF ID since 2026-09-20 (it held a free-text label before). The id of the shelf this sits on, from the one shelf registry that orders the connector catalogue and the app store alike (search, analytics, social, ads, commerce, financial_markets, banking_accounting, crm, productivity, developer, ai, public_data, other). Added 2026-09-20; an unknown value is never returned."},"shelf":{"type":"string","nullable":true,"description":"The app's shelf id when it holds one an app may pick (search, analytics, social, ads, commerce, financial_markets, banking_accounting, crm, productivity, developer, ai, public_data), else null. Added 2026-10-19."},"image_url":{"type":"string","nullable":true},"listed":{"type":"boolean","nullable":true},"visibility":{"type":"string","enum":["private","unlisted","public"],"description":"WHO MAY OPEN the app. A 3rd-party app is 'private' from its first millisecond and stays owner-only until its owner publishes it; first-party apps are seeded 'public'. Written ONLY by PATCH /developer/apps/{id}/visibility, never by a manifest edit."},"indexable":{"type":"boolean","description":"Whether the app's page may be indexed. Curator-controlled, false by default."},"takedown_reason":{"type":"string","nullable":true,"description":"Non-null means autario pulled the app; it is pinned private until the reason is cleared."},"agent_surface":{"type":"object","nullable":true,"description":"The app's self-description for agents ({ mcp_tool, kpis, example_questions }); null for apps without one."}}},"AppLifecycle":{"type":"object","description":"An app's LIFECYCLE state, returned by PATCH /developer/apps/{id}/visibility and GET /developer/apps/{id}/preview. One shape for both, so a client parses the same object whichever it just called.","properties":{"app_id":{"type":"string"},"name":{"type":"string"},"visibility":{"type":"string","enum":["private","unlisted","public"]},"indexable":{"type":"boolean","description":"Whether the app's page may be indexed. Curator-controlled and false by default: publishing is the builder's decision, indexing is autario's."},"taken_down":{"type":"boolean"},"takedown_reason":{"type":"string","nullable":true},"preview_url":{"type":"string","description":"The private page where only the owner can run the app. Never indexed."},"public_url":{"type":"string","nullable":true,"description":"The shareable link, once the app left 'private'. null before that, never a URL that 404s."},"app_url":{"type":"string","description":"/a/<id>: the app alone on the whole screen with its own web app manifest, the link to open on a phone and add to the home screen. Opens for the owner and team always, for others once the app is unlisted or public. Never indexed."},"next_step":{"type":"string","description":"One sentence naming the next call to make."}}},"AppArtifactRef":{"type":"object","description":"The receipt of an artifact write: what was stored, never the spec/data blobs back.","properties":{"ok":{"type":"boolean"},"id":{"type":"string"},"app_id":{"type":"string"},"type":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string","nullable":true},"visibility":{"type":"string","enum":["private","unlisted","public"]},"workspace_id":{"type":"string","nullable":true},"updated_at":{"type":"string","format":"date-time"}}},"DevAppSummary":{"type":"object","description":"One row of GET /developer/apps: the manifest facets the dashboard lists, plus the latest review verdict.","properties":{"id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"integer","enum":[1,2]},"status":{"type":"string","enum":["draft","submitted","approved","published"]},"listed":{"type":"boolean","nullable":true,"description":"The FIRST-PARTY catalog flag. It is not read for an app you own: since 2026-09-08 your app's place in the store is derived from `visibility` alone, so publish with PATCH /developer/apps/{id}/visibility and ignore this field."},"version":{"type":"string","nullable":true},"route":{"type":"string","nullable":true},"tagline":{"type":"string","nullable":true},"category":{"type":"string","nullable":true,"description":"The app's SHELF ID since 2026-09-20 (it held a free-text label before)."},"created_at":{"type":"string","format":"date-time"},"visibility":{"type":"string","enum":["private","unlisted","public"]},"entry_url":{"type":"string","nullable":true},"latest_verdict":{"type":"string","nullable":true,"description":"Verdict of the most recent review, null when never reviewed."},"latest_review_at":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/public/datasets":{"get":{"operationId":"listPublicDatasets","summary":"Search and list public datasets","description":"Discover publicly available datasets. Filter by topic, keyword, or category. No authentication required. Discontinued datasets (source stopped responding) are excluded from listings/search but remain fully readable via their id/slug endpoints. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"q","in":"query","description":"Search term - matches title, description, category, and keywords","schema":{"type":"string"}},{"name":"category","in":"query","description":"Filter by exact category name (e.g. Finance, Weather, Health)","schema":{"type":"string"}},{"name":"visibility","in":"query","description":"Which datasets to search: public (default), private (only your own), or both. Requires authentication; anonymous callers always get public only. Other users' private datasets are never returned.","schema":{"type":"string","enum":["public","private","both"],"default":"public"}},{"name":"offset","in":"query","description":"Rows to skip; pass the previous response's next_offset to walk the catalog. Wins over page when both are sent.","schema":{"type":"integer","default":0,"minimum":0}},{"name":"page","in":"query","description":"1-based page alias of offset (offset = (page-1)*limit)","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"List of public datasets","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total matching datasets regardless of limit/offset"},"count":{"type":"integer","description":"Rows on this page"},"limit":{"type":"integer"},"offset":{"type":"integer"},"page":{"type":"integer"},"pages":{"type":"integer"},"next_offset":{"type":"integer","nullable":true,"description":"Offset of the next page, null when this is the last page"},"has_more":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DatasetMeta"}}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/datasets/{id}":{"get":{"operationId":"getPublicDatasetMeta","summary":"Get metadata for a public dataset","description":"Returns title, description, category, publisher, keywords, and row count. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Dataset UUID or its human-readable slug (the slug seen in /data/<slug> URLs). Both resolve to the same dataset."}],"responses":{"200":{"description":"Dataset metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetMeta"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"No dataset matches that id or slug. Carries error_code:'unknown_dataset' + a hint naming the next call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetNotFound"}}}}}}},"/public/datasets/{id}/schema":{"get":{"operationId":"getPublicDatasetSchema","summary":"Get schema of a public dataset","description":"Returns all column names and their PostgreSQL data types, plus row and column counts, plus which columns carry the time, entity and value ROLES (source_time_col / source_entity_col / source_value_col and the richer column_roles block). Use this BEFORE querying to avoid column name errors, and to know how to read a date: the `endpoints` dates in summary_only are values of source_time_col, so on a period-fact dataset they are period ENDS. Also returns a `semantics` entry per column saying what it MEANS in one sentence (kind, definition, unit, currency, time grain, and where the meaning came from); read it before combining two columns, because autario refuses to combine columns of different kinds. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Dataset UUID or its human-readable slug (the slug seen in /data/<slug> URLs). Both resolve to the same dataset."}],"responses":{"200":{"description":"Dataset schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"No dataset matches that id or slug. Carries error_code:'unknown_dataset' + a hint naming the next call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetNotFound"}}}}}}},"/public/datasets/{id}/changelog":{"get":{"operationId":"getPublicDatasetChangelog","summary":"Structural change history of a public dataset","description":"Every recorded structural change of this dataset, newest first: renames, dropped columns, type changes, added columns and unit changes. A value refresh (same columns, new rows) is deliberately not recorded. Poll this, or the schema_version field on the metadata response, if your code maps our field names into your own. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Dataset UUID or its human-readable slug (the slug seen in /data/<slug> URLs). Both resolve to the same dataset."},{"name":"limit","in":"query","schema":{"type":"integer","default":5,"minimum":1,"maximum":50},"description":"How many entries to return, newest first. Default 5, the same number the dataset page shows."}],"responses":{"200":{"description":"Change history","content":{"application/json":{"schema":{"type":"object","properties":{"dataset_id":{"type":"string","format":"uuid"},"slug":{"type":"string","nullable":true},"schema_version":{"type":"integer","description":"The version the dataset stands at now."},"changelog":{"type":"array","items":{"$ref":"#/components/schemas/DatasetChangelogEntry"}}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"No dataset matches that id or slug. Carries error_code:'unknown_dataset' + a hint naming the next call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetNotFound"}}}}}}},"/public/datasets/slug/{slug}":{"get":{"operationId":"getPublicDatasetBySlug","summary":"Get metadata for a public dataset by slug","description":"Same metadata shape as GET /public/datasets/{id}, addressed by the human-readable slug seen in /data/<slug> URLs. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The dataset's canonical slug (from /data/<slug> URLs or listPublicDatasets results)"}],"responses":{"200":{"description":"Dataset metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetMeta"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"No dataset matches that id or slug. Carries error_code:'unknown_dataset' + a hint naming the next call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetNotFound"}}}}}}},"/public/datasets/{id}/data":{"get":{"operationId":"getPublicDatasetData","summary":"Query rows of a public dataset (THE data endpoint)","description":"Fetch filtered, sorted, paginated rows (or server-side aggregates) from a public dataset. No authentication required for public datasets; with x-api-key + x-api-secret your own private datasets resolve too.\n\n**Filter syntax:** `filter=column:op:value` (SINGULAR `filter`, repeatable). Operators: eq, neq, gt, lt, gte, lte, like. NOTE: the private /datasets/{id}/query endpoint takes `filters` (plural); a mismatched param name is silently ignored and returns unfiltered data.\n\n**Truncation trap:** the default limit is 100. A dataset with thousands of rows silently comes back cut off unless you pass limit explicitly (up to 50000, enough for any complete dataset).\n\n**Aggregations:** `aggregate=fn(col),...` (avg, sum, count, min, max, stddev, median; aliased fn_col) + `groupby=col,...`. Each aggregate is computed on the column's probed basis and `aggregate_meta.aggregates[].basis` names it: `numeric` (the text-stored value cast to a number, never lexicographic), `text` (min/max on a non-numeric column such as an ISO date, compared as text, which sorts chronologically), `not_numeric` (avg/sum/stddev/median on a non-numeric column: null, never a number mined out of the text), `rows` (count). `aggregate_meta.note` spells out any non-numeric basis. `summary_only=true` returns finished per-column stats with NO rows; `non_null_only=true` drops null-value rows. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Dataset UUID or its human-readable slug. Both resolve to the same dataset."},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"minimum":1,"maximum":50000},"description":"Rows per page. Default 100 - pass explicitly for full history (max 50000; larger values are clamped silently)."},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}},{"name":"fields","in":"query","schema":{"type":"string","example":"year,country,gdp_usd"},"description":"Comma-separated column names to return (default: all)"},{"name":"filter","in":"query","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"},"example":["year:gt:2020","country:eq:Germany"]},"description":"Filter expression column:op:value. Repeatable. SINGULAR on this endpoint."},{"name":"sort","in":"query","schema":{"type":"string","example":"year:desc"},"description":"column:asc or column:desc (also aggregate aliases like sum_value:desc)"},{"name":"aggregate","in":"query","schema":{"type":"string","example":"avg(value),count(*)"},"description":"Server-side aggregations; result columns aliased fn_col (avg_value, count_all). min/max on a non-numeric column (e.g. an ISO date) compare the text; see aggregate_meta.aggregates[].basis."},{"name":"groupby","in":"query","schema":{"type":"string","example":"country"},"description":"Comma-separated group-by columns; combine with aggregate"},{"name":"summary_only","in":"query","schema":{"type":"boolean"},"description":"true = finished stats (n/min/max/avg + first/last) and NO raw rows (token saver)"},{"name":"non_null_only","in":"query","schema":{"type":"boolean"},"description":"true = drop rows whose value columns are all null/empty"},{"name":"shadow","in":"query","schema":{"type":"boolean"},"description":"true = include the autario_* shadow columns (canonical time/entity/value join keys)"}],"responses":{"200":{"description":"Rows (or aggregates) with pagination fields","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total matching rows regardless of limit/offset"},"limit":{"type":"integer"},"offset":{"type":"integer"},"data":{"type":"array","items":{"type":"object"}},"query_diagnostics":{"$ref":"#/components/schemas/QueryDiagnostics"}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"No dataset matches that id or slug. Carries error_code:'unknown_dataset' + a hint naming the next call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetNotFound"}}}}}}},"/public/datasets/{id}/export":{"get":{"operationId":"exportPublicDataset","summary":"Download a dataset as CSV","description":"Streams the complete dataset as a CSV attachment. LOGIN OR API KEY REQUIRED (401 without) - the export is account-gated even for public datasets. Serves every public dataset plus the caller's OWN private datasets; a private dataset belonging to somebody else is a 404. 204 when the dataset has no rows. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Dataset UUID or its slug."}],"responses":{"200":{"description":"CSV attachment","content":{"text/csv":{"schema":{"type":"string"}}}},"204":{"description":"Dataset has no rows"},"401":{"description":"Login required to download data. Carries error_code:'login_required' + a hint naming the x-api-key/x-api-secret headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAuthRefusal"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"No dataset matches that id or slug. Carries error_code:'unknown_dataset' + a hint naming the next call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetNotFound"}}}}}}},"/public/datasets/{id}/related":{"get":{"operationId":"getRelatedDatasets","summary":"Data family + topic-related datasets","description":"Returns the data FAMILY (the sibling indicators a single source split out of one concept, e.g. population by age band and sex) and TOPIC-RELATED datasets (other datasets mapping to the same curated topic), each with slug + title for deep-linking. Read-only, cached, public datasets only. Powers the internal-linking block on the dataset profile page. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Dataset UUID or slug. Both forms resolve here, like on every other /public/datasets path (a slug used to 500 on this one)."}],"responses":{"200":{"description":"Family + related datasets","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean"},"topic_key":{"type":"string","nullable":true},"family":{"type":"object","nullable":true,"properties":{"family_key":{"type":"string"},"family_type":{"type":"string"},"member_count":{"type":"integer"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"publisher":{"type":"string","nullable":true}}}}}},"related":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"publisher":{"type":"string","nullable":true},"topic_key":{"type":"string"}}}}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"No dataset matches that id or slug. Carries error_code:'unknown_dataset' + a hint naming the next call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetNotFound"}}}}}}},"/public/datasets/categories":{"get":{"operationId":"listPublicCategories","summary":"List dataset categories with their counts","description":"Every category that carries at least five public datasets, with the count, most populated first. Use the category name verbatim as the ?category filter on GET /public/datasets. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"responses":{"200":{"description":"Categories","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"n":{"type":"integer"}}}}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/datasets/suggest":{"get":{"operationId":"suggestDatasets","summary":"Typeahead suggestions for a partial query","description":"Up to five datasets for a partial search term, for a search box or for an agent narrowing a topic before it commits to a full search. With no q, or when nothing matches, it returns the most relevant datasets in the catalog and says so through matched:false, so an empty answer is never silently indistinguishable from a fallback. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Partial term. Tokens shorter than three characters and common words are ignored."}],"responses":{"200":{"description":"Suggestions","content":{"application/json":{"schema":{"type":"object","properties":{"matched":{"type":"boolean"},"suggestions":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"canonical_slug":{"type":"string"},"publisher":{"type":"string"}}}}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/engine/status":{"get":{"operationId":"getEngineStatus","summary":"Live platform numbers","description":"The live counters: public datasets, rows, publishers, MCP tool count and the tier-1 provider list, plus an MCP health probe. This is the endpoint to quote rather than a number copied from a page, and it is what /status renders. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"responses":{"200":{"description":"Engine status snapshot","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/topics":{"get":{"operationId":"listTopics","summary":"Curated topics with dataset counts","description":"The curated topic list, each with a slug, a name, a one-line lede and how many public datasets map to it. A topic slug is the argument the MCP tool discover_by_topic takes and the path segment of the topic page. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"responses":{"200":{"description":"Topics","content":{"application/json":{"schema":{"type":"object","properties":{"topics":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"lede":{"type":"string"},"count":{"type":"integer"}}}}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/topics/{slug}":{"get":{"operationId":"getTopic","summary":"One topic with its datasets","description":"The topic, up to 200 datasets that map to it with their slugs, publishers and row counts, and the related topics. Build the citable page URL from canonical_slug, never from an id. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Topic slug from GET /public/topics"}],"responses":{"200":{"description":"Topic with datasets","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Unknown topic"}}}},"/public/telemetry":{"post":{"operationId":"postTelemetryBeacon","summary":"First-party funnel beacon","description":"Fire-and-forget first-party telemetry beacon. The browser POSTs a whitelisted funnel event so it lands in the server-side events store independent of GA4/consent/ad-blockers. No authentication. Only the whitelisted event names are accepted (chart_view, csv_download, builder_interaction, signup_wall_shown, dev_early_access_click, dev_early_access_view, chart_started, chart_created, chart_published, publish_failed, shared_footer_click, welcome_action, onboarding_action, connector_export_download, utm_landing); the payload is hard-capped and contains no PII (IP is hashed server-side). Conversions the server owns (dev_early_access_submit, login) are written server-side and are deliberately not accepted here. Returns 204 on a well-formed call. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event"],"properties":{"event":{"type":"string","enum":["chart_view","csv_download","builder_interaction","signup_wall_shown","dev_early_access_click","dev_early_access_view","chart_started","chart_created","chart_published","publish_failed","shared_footer_click","welcome_action","onboarding_action","connector_export_download","utm_landing"]},"slug":{"type":"string","description":"Resource slug the event refers to (e.g. chart slug)"},"kind":{"type":"string","description":"Sub-type for builder_interaction (e.g. entity_changed/range_changed/type_changed)"},"trigger":{"type":"string","description":"What triggered a signup_wall_shown (csv_download / publish / connector_export)"},"connector":{"type":"string","description":"The connector a connector page file CTA or the setup download card belongs to (connector_export, connector_export_download)"},"path":{"type":"string","description":"Originating route"},"utm_source":{"type":"string","description":"utm_landing: the campaign tag of the landing (source)"},"utm_medium":{"type":"string","description":"utm_landing: the channel the link was sent through (email, ads, social, community, partner)"},"utm_campaign":{"type":"string","description":"utm_landing: the program"},"utm_content":{"type":"string","description":"utm_landing: the claim variant (A or B)"},"format":{"type":"string"},"reason":{"type":"string","description":"Why a publish_failed happened (no_description / description_too_short / server_error / exception)"},"via":{"type":"string","description":"Which path published a chart (first_save / visibility_toggle)"},"is_public":{"type":"boolean","description":"Visibility of the chart a chart_created/chart_published refers to"},"shelf":{"type":"string","description":"App Store shelf id an onboarding_action build_tile / build_prompt came from"},"capture":{"type":"boolean","description":"True when fired from an own-pipeline capture render (?capture=1). Such hits are classified as own traffic server-side and excluded from every human-facing metric."}}}}}},"responses":{"204":{"description":"Event accepted (no body)"},"400":{"description":"Missing or non-whitelisted event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/charts/{slug}/analytics":{"get":{"operationId":"getChartAnalytics","summary":"Per-chart engagement counters","description":"Returns engagement counters for a published chart: view_count (HUMAN chart views over the last 30 days; crawlers, bots and autario's own capture renders are excluded, so this reads lower than a raw hit count) and fork_count (lifetime forks from the artifact store). No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Chart engagement counters","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"view_count":{"type":"integer"},"fork_count":{"type":"integer"},"window_days":{"type":"integer"}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/entities/{slug}/profile":{"get":{"operationId":"getEntityProfile","summary":"Deep country profile (Country Profiles app)","description":"For a country slug or ISO-3 code (e.g. germany, united-states, DEU), returns the country's relevant indicators grouped by CATEGORY (Economy, Demographics, Government & Budget, Labor, Trade, Environment, Education & Research). Each category carries an indicators[] row list of MANY demanded indicators, each row with: label, latest value + year, a linked source (publisher + asset id + dataset/timeline URL + primary source + verify URL), a chart link ONLY when a public chart plots this country (else null), and a WORLD-FIRST rank (e.g. #33 of 217 worldwide, with world median + nearest neighbors; G7 members additionally carry their G7 peer rank). Rows with no data for the country are omitted (graceful, never a gap). Each category also carries a back-compat key_indicator + a deterministic factual insight. Also returns headline at-a-glance metrics and a factual overview. Built entirely on the public /public/ontology/* endpoints, so any third-party dev could assemble the same hub. No authentication required. Powers the /country/:slug research hub and the Country Profiles data app. 404 for an unknown country slug. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","example":"germany"},"description":"Country name slug or ISO-3 code (germany, united-states, japan, DEU)"}],"responses":{"200":{"description":"Themed country profile","content":{"application/json":{"schema":{"type":"object","properties":{"entity":{"type":"object","properties":{"code":{"type":"string","example":"DEU"},"slug":{"type":"string","example":"germany"},"display":{"type":"string","example":"Germany"},"type":{"type":"string","example":"country"}}},"canonical_url":{"type":"string"},"overview":{"type":"string","description":"Deterministic factual lede"},"headline_metrics":{"type":"array","items":{"type":"object"}},"themes":{"type":"array","description":"Up to 7 deep categories (Economy, Demographics, Government & Budget, Labor, Trade, Environment, Education & Research). Each carries an indicators[] row list of many demanded metrics.","items":{"type":"object","properties":{"key":{"type":"string","example":"economy"},"label":{"type":"string","example":"Economy"},"indicator_count":{"type":"integer","description":"Number of indicator rows with data for this country"},"indicators":{"type":"array","description":"The deep per-category row list. Rows with no data for the country are omitted.","items":{"type":"object","properties":{"indicator_id":{"type":"string"},"label":{"type":"string","example":"GDP (current US$)"},"value":{"type":"number"},"value_display":{"type":"string","example":"4.53 trillion"},"year":{"type":"string","example":"2023"},"source":{"type":"object","description":"Always present + linked (publisher + dataset/timeline page + primary source + verify URL). asset_id is the row's dataset id, e.g. for a Builder deep link (/builder?dataset=<asset_id>).","properties":{"publisher":{"type":"string","example":"World Bank"},"asset_id":{"type":"string","nullable":true},"dataset_url":{"type":"string"},"dataset_indexable":{"type":"boolean","description":"Whether dataset_url is a page we let search engines index. ABSENT (not false) on snapshots built before this field existed, i.e. absence means unknown, never 'no'."},"primary_source_url":{"type":"string","nullable":true},"verify_url":{"type":"string","nullable":true}}},"chart_url":{"type":"string","nullable":true,"description":"A public /chart/ page that demonstrably plots THIS country, or null when none exists (never another country's chart; use source.asset_id to open the dataset in the Builder instead)."},"chart_image_url":{"type":"string","nullable":true,"description":"Pre-rendered chart PNG preview. Present ONLY when a public chart references the row's dataset; absent otherwise (never fabricated)."},"chart_title":{"type":"string","nullable":true,"description":"The referenced public chart's title. Present only alongside chart_image_url."},"rank":{"type":"object","nullable":true,"description":"Honest ranks, WORLD-FIRST. `global` = the aggregate-excluded WORLDWIDE rank across the indicator's own dataset (emitted only when >=50 countries have values), with the world median and the neighboring countries directly above/below. peer_set/rank/count/median = the G7 peer rank, present ONLY when the country IS a G7 member (a non-member is never framed against the G7). `chart_url` (optional) links a published cross-country ranking chart.","properties":{"peer_set":{"type":"string","example":"G7","description":"Present only for G7 members"},"rank":{"type":"integer","example":3},"count":{"type":"integer","example":7},"median":{"type":"number","nullable":true},"median_display":{"type":"string","nullable":true,"example":"$3.1T"},"global":{"type":"object","nullable":true,"description":"Worldwide rank (countries only; aggregates like WLD/EUU excluded). Absent when fewer than 50 countries have values. `median`/`median_display` = the world median across all ranked countries; `neighbors` = up to 3 countries directly above/below (nearest first), each with a display name + a value formatted like the row value.","properties":{"rank":{"type":"integer","example":33},"count":{"type":"integer","example":217},"median":{"type":"number","nullable":true},"median_display":{"type":"string","nullable":true,"example":"5.9M"},"neighbors":{"type":"object","nullable":true,"properties":{"above":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Spain"},"value_display":{"type":"string","example":"48.6M"}}}},"below":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sudan"},"value_display":{"type":"string","example":"50.4M"}}}}}}}},"chart_url":{"type":"string","nullable":true,"description":"A published cross-country ranking chart for this indicator, when one exists."}}}}}},"key_indicator":{"type":"object","description":"Back-compat: the lead row in the old key_indicator shape"},"peer":{"type":"object","nullable":true,"description":"Back-compat peer-rank context for the lead row (set, median, rank)"},"insight":{"type":"string","nullable":true,"description":"Deterministic factual insight (no LLM)"},"source_datasets":{"type":"array","nullable":true,"description":"Up to 5 links to the autario /data/ pages this category's numbers came from, deduped, in relevance order. Resolved at snapshot-build time and restricted to datasets whose page is INDEXABLE (the same predicate the datasets sitemap uses), so the list is safe to follow and safe to cite. Absent when no qualifying dataset exists and on snapshots built before 2026-08-29.","items":{"type":"object","properties":{"url":{"type":"string","example":"https://autario.com/data/gdp-current-us-world-bank"},"title":{"type":"string","example":"GDP (current US$)"}}}},"prose":{"type":"object","nullable":true,"description":"Optional citeable paragraph (4-6 sentences: lead fact, rank context, trend, one hedged reading, one cross-reference) for this category. Generated off-request by the worker, every number deterministically verified against this category's own rows (skip-not-degrade: absent rather than unverified). Interpretation is hedged, never a named event or normative judgment. Absent on older snapshots.","properties":{"text":{"type":"string","description":"The paragraph (safe to quote verbatim; every number matches a row in indicators[])"},"fact_hash":{"type":"string","description":"Hash of the row facts the paragraph was verified against"},"model":{"type":"string"},"generated_at":{"type":"string","format":"date-time"}}}}}},"intro_prose":{"type":"object","nullable":true,"description":"Optional page-level overview paragraph (5-7 sentences) synthesizing across categories. Same guarantees as the per-category prose: generated off-request, every number deterministically verified against the profile's own rows, hedged interpretation only (skip-not-degrade: absent rather than unverified). Absent on older snapshots.","properties":{"text":{"type":"string","description":"The paragraph (safe to quote verbatim; every number matches a row in the profile)"},"fact_hash":{"type":"string","description":"Hash of the cross-category facts the paragraph was verified against"},"model":{"type":"string"},"generated_at":{"type":"string","format":"date-time"}}},"cite_as":{"type":"string","nullable":true,"description":"One deterministic citation sentence for this page (autario, the country, the publishers this profile actually shows, and the year the data was pulled). No LLM. Absent when no publisher resolved and on snapshots built before 2026-08-29.","example":"Cite as: autario.com, Germany statistics, data from World Bank, Eurostat and IMF (accessed 2026)."},"peers":{"type":"object","nullable":true,"description":"The G7 membership set ({ set, members }) when the country IS a member; null otherwise (a non-member is never framed against the G7)."},"indicator_total":{"type":"integer"},"total_indicator_rows":{"type":"integer","description":"Total indicator rows surfaced across all categories"},"generated_at":{"type":"string","format":"date-time"},"attribution":{"type":"string"}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Unknown country slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/ontology/stats/describe":{"get":{"operationId":"statsDescribe","summary":"Summary statistics for one indicator + entity","description":"Returns n, mean, median, std, min/max, quartiles, skew and a coarse histogram, precomputed server-side from verified source data; no local computation needed. Use FIRST before any deeper test to see sample size and distribution shape. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"parameters":[{"$ref":"#/components/parameters/StatsIndicator"},{"$ref":"#/components/parameters/StatsEntity"},{"$ref":"#/components/parameters/StatsTime"}],"responses":{"200":{"description":"Summary stats + histogram + interpretation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/ontology/stats/pct-change":{"get":{"operationId":"statsPctChange","summary":"Period-over-period percentage change (growth)","description":"Growth rates (YoY-style) with the latest change as a headline figure, precomputed server-side; no local computation needed. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"parameters":[{"$ref":"#/components/parameters/StatsIndicator"},{"$ref":"#/components/parameters/StatsEntity"},{"$ref":"#/components/parameters/StatsTime"},{"$ref":"#/components/parameters/StatsFull"}],"responses":{"200":{"description":"Latest change + optional per-period series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/ontology/stats/rolling":{"get":{"operationId":"statsRolling","summary":"Rolling-window statistics (smoothed trend)","description":"Rolling mean/std/min/max/sum over a configurable window, precomputed server-side; no local computation needed. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"parameters":[{"$ref":"#/components/parameters/StatsIndicator"},{"$ref":"#/components/parameters/StatsEntity"},{"name":"window","in":"query","required":false,"schema":{"type":"integer","example":5},"description":"Window size in periods (2-100, default 5)"},{"name":"op","in":"query","required":false,"schema":{"type":"string","enum":["mean","std","min","max","sum"]},"description":"Rolling operation (default mean)"},{"$ref":"#/components/parameters/StatsTime"},{"$ref":"#/components/parameters/StatsFull"}],"responses":{"200":{"description":"Latest rolling value + optional per-period series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/ontology/stats/correlate":{"get":{"operationId":"statsCorrelate","summary":"Correlation between two indicators for one entity","description":"Pearson + Spearman r with p-values and a plain-language interpretation, precomputed server-side; no local computation needed. Frequencies are auto-aligned to the coarser common grain. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"parameters":[{"$ref":"#/components/parameters/StatsEntity"},{"name":"a","in":"query","required":true,"schema":{"type":"string"},"description":"First indicator id"},{"name":"b","in":"query","required":true,"schema":{"type":"string"},"description":"Second indicator id"},{"$ref":"#/components/parameters/StatsTime"},{"$ref":"#/components/parameters/StatsFull"}],"responses":{"200":{"description":"Correlation stats + interpretation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/ontology/stats/regression":{"get":{"operationId":"statsRegression","summary":"Linear regression y ~ x for one entity","description":"Slope, intercept and R^2 with interpretation, precomputed server-side; no local computation needed. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"parameters":[{"$ref":"#/components/parameters/StatsEntity"},{"name":"y","in":"query","required":true,"schema":{"type":"string"},"description":"Dependent (target) indicator id"},{"name":"x","in":"query","required":true,"schema":{"type":"string"},"description":"Independent (predictor) indicator id"},{"$ref":"#/components/parameters/StatsTime"},{"$ref":"#/components/parameters/StatsFull"}],"responses":{"200":{"description":"Regression stats + interpretation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/ontology/stats/seasonality":{"get":{"operationId":"statsSeasonality","summary":"Seasonal decomposition (trend + seasonal + residual)","description":"Additive decomposition with seasonal amplitude summary, precomputed server-side; no local computation needed. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"parameters":[{"$ref":"#/components/parameters/StatsIndicator"},{"$ref":"#/components/parameters/StatsEntity"},{"name":"period","in":"query","required":false,"schema":{"type":"integer","example":12},"description":"Seasonal period in steps (12=monthly, 4=quarterly); auto-inferred from indicator frequency if omitted"},{"$ref":"#/components/parameters/StatsTime"},{"$ref":"#/components/parameters/StatsFull"}],"responses":{"200":{"description":"Seasonality summary + optional components","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/ontology/stats/calculate":{"get":{"operationId":"statsCalculate","summary":"Derived series from two indicators (ratio, diff, sum, product)","description":"Excel-style derived series (e.g. debt-to-GDP via op=ratio) with summary stats, precomputed server-side; no local computation needed. THE COMBINATION IS CHECKED FIRST: autario refuses to combine two columns of different kinds (a click count and an impression count do not add up) and answers 422 incompatible_semantics naming both columns, the reason and the ops that would work. Every successful response carries a `computation` block (formula, columns with their kinds, rows used, window) so a human can check what was done. Read the `semantics` block of the schema endpoint to know a column's kind up front. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"parameters":[{"$ref":"#/components/parameters/StatsEntity"},{"name":"a","in":"query","required":true,"schema":{"type":"string"},"description":"First indicator id (numerator for ratio)"},{"name":"b","in":"query","required":true,"schema":{"type":"string"},"description":"Second indicator id (denominator for ratio)"},{"name":"op","in":"query","required":false,"schema":{"type":"string","enum":["ratio","ratio_pct","diff","sum","product"]},"description":"Operation (default ratio)"},{"name":"override","in":"query","required":false,"schema":{"type":"boolean"},"description":"Compute a combination that was refused as incompatible. Requires `reason`."},{"name":"reason","in":"query","required":false,"schema":{"type":"string"},"description":"Why the refused combination is correct here. Returned inside the response so a human can audit the decision."},{"$ref":"#/components/parameters/StatsTime"},{"$ref":"#/components/parameters/StatsFull"}],"responses":{"200":{"description":"Derived-series summary + optional per-time series, plus `semantics` (what was combined) and `computation` (what was done)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"422":{"description":"The two columns are different kinds of number and autario will not combine them. Body: error_code 'incompatible_semantics', a sentence, reason_code, left/right column semantics, and `allowed` listing the ops that WOULD work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncompatibleSemantics"}}}}}}},"/public/ontology/stats/what-matters":{"get":{"operationId":"statsWhatMatters","summary":"Rank which metrics best explain an outcome","description":"Auto-selects candidate indicators from the ontology (or takes candidates=) and ranks them against the outcome with confidence labels (strong/suggestive/weak/inconclusive), precomputed server-side; no local computation needed. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"parameters":[{"$ref":"#/components/parameters/StatsEntity"},{"name":"outcome","in":"query","required":true,"schema":{"type":"string"},"description":"Indicator id of the outcome metric"},{"name":"candidates","in":"query","required":false,"schema":{"type":"string"},"description":"Optional comma-separated candidate indicator ids (auto-selected when omitted)"},{"$ref":"#/components/parameters/StatsTime"}],"responses":{"200":{"description":"Confidence-labeled ranking + scope + interpretation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/ontology/stats/lag-analysis":{"get":{"operationId":"statsLagAnalysis","summary":"Lead/lag cross-correlation between two indicators","description":"Cross-correlation at lags -N..+N answering \"does A lead or lag B?\", precomputed server-side; no local computation needed. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"parameters":[{"name":"a","in":"query","required":true,"schema":{"type":"string"},"description":"First indicator id (candidate leading series)"},{"name":"b","in":"query","required":true,"schema":{"type":"string"},"description":"Second indicator id (candidate lagging series)"},{"$ref":"#/components/parameters/StatsEntity"},{"name":"max_lag","in":"query","required":false,"schema":{"type":"integer","example":5},"description":"Max lag in periods (1-20, default 5)"},{"$ref":"#/components/parameters/StatsTime"}],"responses":{"200":{"description":"Per-lag correlations + best lag + direction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/ontology/stats/find-drivers":{"post":{"operationId":"statsFindDrivers","summary":"Rank candidate indicators by how well they predict a target","description":"Correlates + regresses each candidate against the target KPI and returns a ranked list (r, p-value, R^2), precomputed server-side; no local computation needed. Max 30 candidates. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entity","target_indicator","candidates"],"properties":{"entity":{"type":"string","example":"DEU"},"target_indicator":{"type":"string","description":"The KPI to explain"},"candidates":{"type":"array","items":{"type":"string"},"description":"Candidate indicator ids (max 30)"},"time":{"type":"string","example":"2010-2023"}}}}}},"responses":{"200":{"description":"Ranked drivers + interpretation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/ontology/stats/decompose-drivers":{"post":{"operationId":"statsDecomposeDrivers","summary":"Joint driver decomposition with collinearity honesty","description":"Fits ONE multiple regression of the target on ALL candidates jointly, so each coefficient is the candidate's effect holding the other candidates constant. Candidates too entangled to separate (VIF > 5 or pairwise |r| > 0.8, e.g. a promo that always ran in warm weeks) are flagged not_separable with named partners instead of ranked with a confident wrong number. Also reports the best lead/lag per candidate. 2-15 candidates. Omit entity for entity-less private series. Deterministic, precomputed server-side. No authentication required for public data; authenticate to use your own private datasets. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_indicator","candidates"],"properties":{"entity":{"type":"string","example":"DEU","description":"Optional entity code; omit for entity-less private KPI series"},"target_indicator":{"type":"string","description":"The KPI to explain"},"candidates":{"type":"array","items":{"type":"string"},"description":"Candidate indicator ids decomposed jointly (2-15)"},"time":{"type":"string","example":"2024-2026"},"max_lag":{"type":"integer","example":5,"description":"Max lead/lag periods scanned per candidate (0 disables, default 5, max 20)"},"full":{"type":"boolean","description":"When true, the response additionally carries series {t[], actual[], fitted[]}: the aligned target values and the joint model's fitted values (token-heavy; omit unless you plot actual vs fitted)"}}}}}},"responses":{"200":{"description":"Joint model + separable drivers (ranked by standardized effect) + not_separable flags + lead/lag + interpretation. With full=true also series {t, actual, fitted} for an actual-vs-fitted view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/ontology/stats/coverage":{"get":{"operationId":"statsCoverage","summary":"Can these series run, and for which entities?","description":"The offer gate: ask BEFORE decompose-drivers instead of discovering a dead series after it. Returns per series the usable time points for the requested entity (counted with the SAME filter the run uses), whether that clears the role minimum (target 10 points, candidate 3), and entity_options: the curated major countries where EVERY selected series has enough data. entity_options never contains aggregate region codes (EAS/SSF/...) or tail countries, so a UI built on it cannot offer a run that dies empty. Read-only, deterministic, no LLM. Authenticate to include your own private datasets. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Stats"],"parameters":[{"name":"target","in":"query","schema":{"type":"string"},"description":"Indicator id of the KPI to explain (role minimum: 10 usable points)"},{"name":"candidates","in":"query","schema":{"type":"string"},"example":"id2,id3","description":"Comma-separated candidate indicator ids, max 15 (role minimum: 3 usable points each)"},{"name":"entity","in":"query","schema":{"type":"string"},"example":"DEU","description":"Entity to probe; omit to ask only which entities are possible"},{"name":"time","in":"query","schema":{"type":"string"},"example":"2020-2026"}],"responses":{"200":{"description":"Per-series usable point counts + role verdicts, entity_options (verified majors), runnable, and honest blockers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/markets/{ticker}/datasets":{"get":{"operationId":"getMarketDatasets","summary":"Resolve a ticker to its datasets","description":"Maps a stock ticker to its canonical price dataset and SEC fundamental datasets (dataset_id + slug for each), so an app can then read them via /public/datasets/{id}/data. The price series is not surfaced as an ontology indicator, which is why this resolver exists. No authentication required. FRESHNESS: every advertised entry (price and each fundamentals item) carries the same three honesty fields - row_count (live), last_date (the newest value on that dataset's time axis) and is_discontinued (the source stopped answering). A discontinued dataset is MARKED, not withheld, because its URL is a permanent contract and its rows are still valid history; check last_date against today before printing any value as a current figure. price is null when the ticker is not yet held (call POST /public/ingest/ticker to pull it). name is the display company name (null for a multi-class/foreign/unresolved ticker). fundamentals includes a \"Weighted Avg Diluted Shares\" entry (unit: shares) - the calc-EPS denominator dataset - so an externalized client can compute Diluted EPS identically to the bespoke app (pin filter=period_months:eq:3 on that dataset: it mixes 3/6/9/12-month averages and the newest row is usually a year-to-date average). Rows carry cy/cq (CALENDAR year/quarter from SEC's frame; null on year-to-date rows) and period_months (3/6/9/12, null for point-in-time facts); there are NO fiscal-year columns - for off-calendar filers calendar and fiscal years differ, so answer fiscal-year questions by summing the quarters inside the fiscal start/end range, or as a trailing-twelve-month sum of the four most recent quarters of an additive metric. Read each row's value_basis (reported vs derived from the annual identity) before trusting it. Do NOT multiply this endpoint's price.close by a \"Shares Outstanding\" fundamentals value for a historical Market Cap: close is split-adjusted to today's share basis while Shares Outstanding is as-reported for its own date, so the product understates history by the cumulative split factor (Apple ~28x across 2014+2020); use a same-date share count and an unadjusted price, or compare only the latest period. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","example":"AAPL"}}],"responses":{"200":{"description":"Resolved datasets for the ticker. 200 also for an unknown ticker; check `found`.","content":{"application/json":{"schema":{"type":"object","properties":{"ticker":{"type":"string"},"name":{"type":"string","nullable":true,"description":"Display company name; null for a multi-class/foreign/unresolved ticker"},"price":{"type":"object","nullable":true,"properties":{"dataset_id":{"type":"string","format":"uuid"},"slug":{"type":"string","nullable":true},"row_count":{"type":"integer","nullable":true,"description":"Rows the dataset holds RIGHT NOW (live count, not a cached stat). null only when the count could not be taken."},"dataset_url":{"type":"string","nullable":true,"description":"The citable page for this dataset (https://autario.com/data/<slug>). Put this in a citation instead of constructing a URL from the id: /data/<uuid> does not resolve."},"last_date":{"type":"string","nullable":true,"description":"The newest value on this dataset's time axis, measured in the SAME round trip as row_count. For a price series that is the last trading day it holds; for an SEC series the newest period end. null when it could not be measured. This is the DATA-POINT freshness fact (see last_refreshed_at for the ingest one): compare it against today before presenting any figure as current."},"last_refreshed_at":{"type":"string","format":"date-time","nullable":true,"description":"INGEST FRESHNESS: when autario last pulled this source and wrote rows (null if never re-ingested). A DIFFERENT fact from last_date: last_date is how new the newest data point is, this is how recently we looked. A source that quietly stopped publishing keeps a fresh last_refreshed_at and an old last_date, which is the case you cannot detect from the data alone. Caveat: a source answering 304 Not Modified is skipped without a write, so the stamp can lag the last CHECK by a refresh cycle; it never runs ahead of the data."},"is_discontinued":{"type":"boolean","description":"true when the SOURCE stopped answering and the series is no longer updated. The dataset stays fully readable (its URL is a permanent contract) and its rows stay valid history, but last_date is the newest value there is. Discontinued datasets are excluded from /public/datasets listings and search; this resolver still returns them, marked."}}},"fundamentals":{"type":"array","description":"SEC fundamental datasets, statement-ordered. Includes a \"Weighted Avg Diluted Shares\" entry (unit: shares) used as the Diluted-EPS denominator. Synthetic Market Cap is excluded (it has no ingested dataset). VARIABLE LENGTH: a filer without a given concept simply has no entry, so never index this array positionally. A held dataset can also be temporarily EMPTY; every entry carries row_count, so filter on row_count > 0 before reading /public/datasets/{id}/data.","items":{"type":"object","properties":{"dataset_id":{"type":"string","format":"uuid"},"label":{"type":"string","example":"Revenue"},"unit":{"type":"string","example":"USD"},"slug":{"type":"string","nullable":true},"row_count":{"type":"integer","nullable":true,"description":"Rows the dataset holds RIGHT NOW (live count, not a cached stat). 0 means the dataset exists and is public but currently holds nothing; null means the count could not be taken."},"dataset_url":{"type":"string","nullable":true,"description":"The citable page for this dataset (https://autario.com/data/<slug>). Put this in a citation instead of constructing a URL from the id: /data/<uuid> does not resolve."},"last_date":{"type":"string","nullable":true,"description":"The newest value on this dataset's time axis (for SEC series: the newest period end), measured in the same round trip as row_count. null when it could not be measured."},"last_refreshed_at":{"type":"string","format":"date-time","nullable":true,"description":"INGEST FRESHNESS: when autario last pulled this source and wrote rows (null if never re-ingested). A DIFFERENT fact from last_date: last_date is how new the newest data point is, this is how recently we looked. A source that quietly stopped publishing keeps a fresh last_refreshed_at and an old last_date, which is the case you cannot detect from the data alone. Caveat: a source answering 304 Not Modified is skipped without a write, so the stamp can lag the last CHECK by a refresh cycle; it never runs ahead of the data."},"is_discontinued":{"type":"boolean","description":"true when the SOURCE stopped answering. The rows stay readable as history; last_date is the newest value there is."}}}},"found":{"type":"boolean","description":"true iff at least one dataset is held for the ticker. The endpoint answers 200 either way, so this is the field to branch on."},"error_code":{"type":"string","enum":["unknown_ticker","no_datasets_held"],"description":"Only when found is false. unknown_ticker = the symbol resolves to nothing; no_datasets_held = the company is known but no dataset is stored yet."},"hint":{"type":"string","description":"Present when found is false (names the next call that fixes it), when found is true but at least one advertised dataset currently holds 0 rows, and when at least one advertised dataset is discontinued (names which ones, in plain prose)."}},"required":["ticker","found"]}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/stocks/screener":{"get":{"operationId":"getStockScreener","summary":"Screen and rank stocks (growth, profitability, value, 52-week range, 200-week moving average)","description":"The REST twin of the screen_stocks MCP tool. Answers from daily snapshots of two derived datasets: fundamental screens (SEC EDGAR filings: 1-year TTM revenue and EPS growth, net margin, growth score) and price screens (Yahoo Finance daily closes adjusted for splits and dividends: earnings yield, distance from the 52-week high and low, distance from the 200-week moving average). Pass a preset or at least one filter. A company without every input of the screen is not listed, never ranked as zero. Every row carries company_url and the source dataset URLs of its inputs. as_of=YYYY-MM-DD answers the newest snapshot on or before that day, for backtests. No authentication required. 400 with a sentence for an unknown preset, a planned preset (dividend, insider-buying), an unknown column or malformed filters. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"preset","in":"query","required":false,"description":"growth | profitability | value | near-52-week-high | near-52-week-low | below-200-week-ma | most-held-by-13f","schema":{"type":"string","example":"growth"}},{"name":"filters","in":"query","required":false,"description":"JSON object of column ranges, e.g. {\"net_margin\":{\"min\":10},\"pct_vs_200w_ma\":{\"max\":0}}. Columns: revenue_growth_1y, eps_growth_1y, net_margin, growth_score, earnings_yield, pct_from_52w_high, pct_from_52w_low, pct_vs_200w_ma, holders_13f.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Column to order by. Default: the rank column of the preset, else the first filter.","schema":{"type":"string"}},{"name":"order","in":"query","required":false,"description":"asc or desc. Default: best first.","schema":{"type":"string","enum":["asc","desc"]}},{"name":"limit","in":"query","required":false,"description":"Rows, default 25, max 200.","schema":{"type":"integer","example":25}},{"name":"as_of","in":"query","required":false,"description":"YYYY-MM-DD; the newest daily snapshot on or before this day.","schema":{"type":"string","example":"2026-11-05"}}],"responses":{"200":{"description":"The screen.","content":{"application/json":{"schema":{"type":"object","properties":{"preset":{"type":"object","nullable":true,"description":"id, name, status (measured: live | no_snapshot_yet | no_rows), kind (fundamental or price), formula, source line, page_url."},"sort":{"type":"string"},"order":{"type":"string"},"filters":{"type":"object"},"as_of":{"type":"object","description":"Snapshot day per dataset read."},"total":{"type":"integer","description":"Rows matching before the limit."},"returned":{"type":"integer"},"empty_reason":{"type":"string","description":"Only when total is 0: no_snapshot_yet | no_snapshot_for_as_of | no_rows | no_match.","enum":["no_snapshot_yet","no_snapshot_for_as_of","no_rows","no_match"]},"message":{"type":"string","description":"Only when total is 0: one sentence saying why the screen is empty."},"rows":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Unknown or planned preset, unknown column, malformed filters or as_of."},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/stocks/screener/presets":{"get":{"operationId":"getStockScreenerPresets","summary":"The stock screen presets and factors with their formulas","description":"Every preset with its MEASURED status (live = the newest daily snapshot holds rows, with rows and as_of; no_snapshot_yet = nothing built yet; no_rows = built, no company qualifies; planned = waits for data), its formula, its source line and its page URL, plus every factor column with its formula and whether it reads a share price. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"responses":{"200":{"description":"{ presets: [...], factors: [...] }"},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/investors":{"get":{"operationId":"listInvestors","summary":"Investors tracked from SEC Form 13F","description":"The REST twin of the list_investors MCP tool. Every well-known Form 13F filer autario tracks, with the latest reported quarter end, filing date, total reported value, number of positions and largest holding (null fields until a filer is ingested). Form 13F is filed up to 45 days after the quarter ends, so positions are as of the quarter end. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"responses":{"200":{"description":"{ investors: [{ slug, display, cik, url, api_url, quarter_end, filed_date, total_value_usd, positions, top_holding }], count, note }"},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/investors/{slug}":{"get":{"operationId":"getInvestorProfile","summary":"One investor's 13F hub profile","description":"The persisted profile behind /investor/{slug}: latest quarter end, filing date, lag note, largest 100 holdings, sector split, quarter-over-quarter moves and reported value by quarter. A not yet computed profile answers a short-cached placeholder. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","example":"berkshire-hathaway"}}],"responses":{"200":{"description":"Investor profile"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Unknown investor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/investors/{slug}/portfolio":{"get":{"operationId":"getInvestorPortfolio","summary":"Every position of one investor for one quarter (Form 13F)","description":"The REST twin of the get_investor_portfolio MCP tool. Reads the filer's dataset: one row per security with cusip, issuer, company_ticker (set only by an exact issuer-name match against the autario company roster), title_of_class, put_call, value_usd, shares, pct_of_portfolio, shares_change, shares_change_pct, is_new and is_closed (a closed position is a zero row in the quarter it disappeared). Largest first. Amendments applied; pre-2023 values converted from thousands to dollars. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Investor slug, display name or SEC CIK.","schema":{"type":"string","example":"berkshire-hathaway"}},{"name":"quarter","in":"query","required":false,"description":"Quarter end (2026-06-30) or label (2026-Q2). Default: latest.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max holdings (default 500, max 5000).","schema":{"type":"integer"}}],"responses":{"200":{"description":"{ investor, quarter_end, quarter, filed_date, accession, lag_note, total_value_usd, positions, closed_positions, quarters_available, holdings[], truncated, dataset_url, source }"},"400":{"description":"Malformed quarter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Unknown investor, not ingested yet, or quarter not in the data (quarters_available lists the rest)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/investors/holders/{ticker}":{"get":{"operationId":"whoHolds","summary":"Which tracked investors hold a company (Form 13F)","description":"The REST twin of the who_holds MCP tool. Holders of a company on the autario company roster among the tracked investors, from their latest Form 13F: value_usd, shares, pct_of_portfolio, shares_change, is_new, quarter_end, filed_date. A ticker outside the roster answers an empty list with a note (holdings are linked by exact issuer name, never guessed). Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","example":"AAPL"}}],"responses":{"200":{"description":"{ ticker, company_url, covered_investors, holders[], note }"},"400":{"description":"Malformed ticker","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/politicians":{"get":{"operationId":"listPoliticians","summary":"US House members with reported stock trades (Periodic Transaction Reports)","description":"The REST twin of the list_politicians MCP tool. Every House member with a Periodic Transaction Report (STOCK Act) in the ingested years, with trades read, purchases, sales, most traded asset, latest report date and whether the hub page is indexable. Slugs are first-last-state. Senate trades are not included. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"responses":{"200":{"description":"{ politicians: [{ slug, display, state, state_district, url, api_url, trades_total, purchases, sales, latest_trade_date, latest_filing_date, filings_total, most_traded, indexable }], count, chamber, note }"},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/developers/{handle}":{"get":{"operationId":"getDeveloperProfile","summary":"A developer's public page","description":"The model behind /developers/{handle}: display name, bio, links (website, GitHub, X, LinkedIn, each with its rel), the developer's published apps (in the app store, review passed) with a user count, and their public datasets with row counts. `earned` is true once the developer has one published app or one public dataset; only then is the page indexable and are its links followed. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string","example":"ada"}}],"responses":{"200":{"description":"{ handle, url, display_name, bio, links: [{ kind, label, url, rel }], earned, indexable, apps_published, datasets_public, apps: [{ id, name, tagline, url, users }], datasets: [{ id, title, description, url, rows, updated }] }"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"No developer has this handle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/politicians/overview":{"get":{"operationId":"getPoliticianTradesOverview","summary":"House trades at a glance: most active members, biggest recent trades, latest filings","description":"The overview of the Politician Trades app: coverage (members, trades, how many could be scored against the S&P 500), the equal-weighted result of all scored purchases and sales, the most active members, the largest trades of the last 90 days by official amount range, the latest filings, purchases and sales by month and by party. Built once a day; every scored trade is also a row of the public performance dataset. No authentication required. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"responses":{"200":{"description":"{ chamber, benchmark, as_of, coverage, buys, sells, most_active, biggest_recent, latest_filings, top, bottom, by_month, by_party, method, sources }"},"402":{"$ref":"#/components/responses/PlanLimit"},"503":{"description":"Not built yet"}}}},"/public/politicians/leaderboard":{"get":{"operationId":"getPoliticianLeaderboard","summary":"House members ranked by how their reported purchases did against the S&P 500","description":"The REST twin of the politician_leaderboard MCP tool. One row per member: rank, the ranked value, purchases scored, average return and average excess over the S&P 500 since each purchase and after 30, 90 and 365 days, the share of purchases that beat the index (hit rate), number of trades and the traded volume band (sum of the official lower and upper bounds). Entry is the close of the first trading day on or after the reported transaction date; price returns, dividends on neither side; every trade weighs the same. Only stock trades whose printed ticker autario holds prices for are scored. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"metric","in":"query","required":false,"description":"avg_excess_since (default) | avg_excess_30 | avg_excess_90 | avg_excess_365 | hit_rate_30 | hit_rate_90 | hit_rate_365 | hit_rate_since | avg_return_since","schema":{"type":"string","example":"hit_rate_90"}},{"name":"min_scored","in":"query","required":false,"description":"Minimum scored purchases for a rank, default 5.","schema":{"type":"integer","example":5}},{"name":"party","in":"query","required":false,"description":"R | D | I","schema":{"type":"string","example":"D"}},{"name":"limit","in":"query","required":false,"description":"Max members, default 100, max 500.","schema":{"type":"integer","example":100}}],"responses":{"200":{"description":"{ chamber, benchmark, as_of, metric, min_scored, total, members: [{ rank, value, scored_for_metric, slug, display, state_district, party, title, url, trades, scored, purchases, sales, volume, buys, sells }], coverage, method }"},"400":{"description":"Unknown metric"},"402":{"$ref":"#/components/responses/PlanLimit"},"503":{"description":"Not built yet"}}}},"/public/politicians/stocks":{"get":{"operationId":"getPoliticianStocks","summary":"The stocks House members traded most, with who and when","description":"Per printed ticker: purchases, sales, number of members, the split by party, the average excess over the S&P 500 of the scored purchases, and the latest trades with member, direction, date and amount range. Most traded first. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Max tickers, default 50, max 150.","schema":{"type":"integer","example":50}}],"responses":{"200":{"description":"{ chamber, benchmark, as_of, total, stocks: [{ ticker, asset, company_url, priced, trades, purchases, sales, members, party, avg_excess_since_buys, scored_buys, latest }], method }"},"402":{"$ref":"#/components/responses/PlanLimit"},"503":{"description":"Not built yet"}}}},"/public/politicians/{slug}":{"get":{"operationId":"getPoliticianProfile","summary":"One House member's trade hub profile","description":"The REST twin of the get_politician_performance MCP tool and the persisted profile behind /politician/{slug}. `performance` holds the member's scored purchases and sales against the S&P 500 (average return, average excess, hit rates after 30, 90 and 365 days, the weekly series of the portfolio of reported purchases next to the index, coverage, filing delay); `entity` carries party, committees and committee roles from the Clerk's member list when the member sits in the current House. Recent 250 trades, each with its filing delay and return since, most traded assets, purchases and sales by month, amount-range and owner counts, filings not read (paper filings published as scanned images, with their PDF link). The slug may also be a full or last name that matches exactly one member. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","example":"josh-gottheimer-nj"}}],"responses":{"200":{"description":"Politician profile"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Unknown politician","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/politicians/{slug}/trades":{"get":{"operationId":"getPoliticianTrades","summary":"Every reported trade of one House member in a window","description":"The REST twin of the get_politician_trades MCP tool. Reads the yearly PTR datasets: one row per transaction with transaction_date, notification_date, filing_date, owner (self, spouse, joint, dependent_child), asset as printed, ticker when the filer printed one, asset_type code, transaction_type (purchase, sale, partial_sale, exchange), amount_range with amount_min and amount_max (the official bracket; amount_max is null for the open-ended top brackets), doc_id and pdf_url. Newest first. Reports lag the trade by up to 45 days. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","example":"josh-gottheimer-nj"}},{"name":"window","in":"query","required":false,"description":"30d | 90d | 1y | 2y | all, by transaction date. Default 1y.","schema":{"type":"string","example":"1y"}},{"name":"limit","in":"query","required":false,"description":"Max trades, default 200, max 2000.","schema":{"type":"integer","example":200}}],"responses":{"200":{"description":"{ politician, url, window, since, total, trades: [...], note }"},"400":{"description":"Bad window"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Unknown politician"}}}},"/public/politicians/trades/{ticker}":{"get":{"operationId":"getCongressTrades","summary":"House members' trades in one stock","description":"The REST twin of the congress_trades MCP tool. Every read transaction whose printed ticker is this roster company's exact ticker, across members: totals of members, purchases and sales in the window plus the trades, newest first, each with the member, its hub URL and the source PDF. Senate trades are not included. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","example":"NVDA"}},{"name":"window","in":"query","required":false,"description":"30d | 90d | 1y | 2y | all. Default 1y.","schema":{"type":"string","example":"1y"}},{"name":"limit","in":"query","required":false,"description":"Max trades, default 200, max 2000.","schema":{"type":"integer","example":200}}],"responses":{"200":{"description":"{ ticker, window, since, total, members, purchases, sales, trades: [...], note }"},"400":{"description":"Bad ticker or window"},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/stocks/{ticker}":{"get":{"operationId":"getStockSnapshot","summary":"Latest verified stock metrics for one ticker","description":"The REST twin of the get_company_snapshot MCP tool: one small call returns only the metrics you ask for, already computed, instead of a price series you have to reduce yourself (the calculator contract). No authentication required. `metrics` is a comma-separated subset of price, open, high, low, volume, perf_1d, perf_1w, perf_1m, perf_3m, perf_1y, perf_ytd, latest_date; unknown names are dropped and an entirely unknown list answers 400 with the allowed set. Performance figures are percentages rounded to two decimals. perf_1d/1w/1m/3m/1y are computed over TRADING days (perf_1w is 5 sessions back, perf_1m 21, perf_1y 252), so they are approximate windows, not calendar ones; perf_ytd is the one calendar window, measured against the last close before 1 January of the latest session's year, and the response names that base session as perf_ytd_base_date. The response carries citation_url and dataset_id, so every number stays traceable to the dataset page it came from. Read latest_date before presenting anything as a current price: the snapshot reflects the last session held, not necessarily today. FUNDAMENTALS: for a covered US company any row key of its /company page is a metric too (revenue, gross-margin, roe, price-to-book, dividend-yield, free-cash-flow, revenue-growth-5y, ...), returned under fundamentals with value, period, formula and source; metrics=fundamentals returns every row; unknown names are listed in unknown_metrics. 404 carries error_code unknown_ticker (nothing held) or no_price_history, with a hint naming the next call (POST /public/ingest/ticker pulls a missing ticker). For values over time use /public/stocks/{ticker}/history. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","example":"AAPL"}},{"name":"metrics","in":"query","required":false,"description":"Comma-separated metric names. Default: price,perf_1d,perf_ytd.","schema":{"type":"string","example":"price,perf_1d,perf_ytd"}}],"responses":{"200":{"description":"Snapshot carrying ONLY the requested metrics plus the identity/provenance fields.","content":{"application/json":{"schema":{"type":"object","properties":{"ticker":{"type":"string"},"name":{"type":"string","description":"Display company name (falls back to the ticker)."},"price":{"type":"number","description":"Latest close. Present only when requested."},"open":{"type":"number","description":"Latest session open. Present only when requested."},"high":{"type":"number","description":"Latest session high. Present only when requested."},"low":{"type":"number","description":"Latest session low. Present only when requested."},"volume":{"type":"integer","description":"Latest session volume. Present only when requested."},"perf_1d":{"type":"number","nullable":true,"description":"Percent change vs the previous session. null when the history is too short."},"perf_1w":{"type":"number","nullable":true,"description":"Percent change vs 5 trading sessions back."},"perf_1m":{"type":"number","nullable":true,"description":"Percent change vs 21 trading sessions back."},"perf_3m":{"type":"number","nullable":true,"description":"Percent change vs 63 trading sessions back."},"perf_1y":{"type":"number","nullable":true,"description":"Percent change vs 252 trading sessions back."},"perf_ytd":{"type":"number","nullable":true,"description":"Year-to-date: percent change vs the last close held strictly before 1 January of the latest session's year. null when no prior-year close is held."},"perf_ytd_base_date":{"type":"string","nullable":true,"description":"The session perf_ytd is measured against (normally the last trading day of the previous year). Present whenever perf_ytd was requested; null when perf_ytd is null."},"latest_date":{"type":"string","description":"The session the figures come from. Compare it against today before calling a price current."},"source":{"type":"string","example":"stooq.com via Autario"},"citation_url":{"type":"string","description":"The dataset page to cite."},"dataset_id":{"type":"string","format":"uuid","description":"The price dataset behind the numbers; read it via /public/datasets/{id}/data for the full series."},"fundamentals":{"type":"object","description":"Requested fundamental metrics keyed by row key: { label, value, display, unit, period, category, formula?, source }. Present only when a fundamental metric was requested.","additionalProperties":{"type":"object"}},"unknown_metrics":{"type":"array","items":{"type":"string"},"description":"Requested names that are neither a price metric nor a fundamental row of this company."}},"required":["ticker","citation_url"]}}}},"400":{"description":"No valid metric name in `metrics` (the body names the allowed set)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Nothing held for this ticker: error_code unknown_ticker (or no_price_history when the price dataset has no rows), hint names the next call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/stocks/{ticker}/history":{"get":{"operationId":"getStockHistory","summary":"Backtest-ready price + fundamentals history, point-in-time","description":"Daily prices joined with SEC fundamentals AS THEY WERE KNOWN on each day: a figure applies from the day it was first filed (first_filed), never from its period end, and a restatement applies from its own filing date; rows ingested before first_filed existed apply from their latest filing date (later, never earlier). Income and cash-flow fields are trailing-12-month sums of the four latest quarters known on that day; balance fields are the latest known balance; per-share fields and shares_outstanding are on today's split basis, like adj_close. Derived fields (market_cap, pe_ratio, price_to_book, price_to_sales, dividend_yield) are computed per day and their formula is in the formulas field. No authentication. The REST twin of the get_company_fundamentals MCP tool. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","example":"AAPL"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated: open, high, low, close, adj_close, volume, revenue, gross_profit, research_and_development, sga, operating_income, interest_expense, income_tax, net_income, operating_cash_flow, capital_expenditure, depreciation_amortization, total_assets, total_liabilities, stockholders_equity, cash_and_equivalents, long_term_debt, shares_outstanding, eps_diluted, dividends_per_share, market_cap, pe_ratio, price_to_book, price_to_sales, dividend_yield. Default: close,adj_close,revenue,net_income,eps_diluted.","schema":{"type":"string","example":"adj_close,eps_diluted,pe_ratio"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"interval","in":"query","required":false,"description":"daily (default), monthly or quarterly: the row of the last trading day of each period.","schema":{"type":"string","enum":["daily","monthly","quarterly"]}},{"name":"format","in":"query","required":false,"description":"json (default) or csv (header date + fields).","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"One row per trading day (or per period with interval); a field unknown on that day is null.","content":{"application/json":{"schema":{"type":"object","properties":{"ticker":{"type":"string"},"name":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}},"interval":{"type":"string"},"from":{"type":"string","nullable":true},"to":{"type":"string","nullable":true},"point_in_time":{"type":"object","description":"The availability rule, in words."},"formulas":{"type":"object","additionalProperties":{"type":"string"}},"not_held":{"type":"array","items":{"type":"string"},"description":"Requested (or needed) fields this company has no dataset for."},"sources":{"type":"object","description":"Dataset page per field."},"citation_url":{"type":"string","nullable":true},"rows":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"}},"additionalProperties":{"type":"number","nullable":true}}}},"required":["ticker","fields","rows","point_in_time"]}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"error_code unknown_field (body lists allowed) or bad_interval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"error_code unknown_ticker, with a hint naming the next call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/ingest/ticker":{"post":{"operationId":"ingestTicker","summary":"On-demand live ingest of a ticker","description":"Fetches a not-yet-held US ticker (Yahoo price + SEC fundamentals) through the same quality gates as the nightly catalog grow, then reports readiness. API KEY REQUIRED. Price is the validity gate: no price means the symbol is not a real ticker (status:'invalid', nothing ingested). Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Public"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ticker"],"properties":{"ticker":{"type":"string","example":"AAPL"}}}}}},"responses":{"200":{"description":"Ingest result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ready","price-only","invalid"]},"ticker":{"type":"string"},"priceAvailable":{"type":"boolean"},"hasFundamentals":{"type":"boolean"}}}}}},"401":{"description":"API key required. Carries error_code:'api_key_required' + a hint naming the x-api-key/x-api-secret headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAuthRefusal"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/me/datasets":{"get":{"operationId":"listMyDatasets","summary":"List every dataset YOU own, with a CSV URL per row","description":"Your own data: the tables your connectors write, your uploads, the derived per-client marketing table, and the tables other accounts shared with you (read-only). Not the catalog | use GET /datasets for that, which also returns public datasets.\n\nThis is the one URL a Power BI or Excel workbook points at. The Web connector expands the `data` list and each row carries `csv_url`, so one connection reaches every table instead of one connection per dataset.\n\n`kind` is `connector`, `upload`, `derived` or `shared`. `shared` is a table ANOTHER account shared with you (read-only); `shared_by` names that owner and is null on every table you own. A `brand` or `instances` narrowing leaves shared tables out, since they belong to none of your brands. `brand` names the brand a connection reports for (null on a personal setup and on an upload). `columns` is the column list of the table, so a caller does not need a schema call per dataset.\n\nNot paginated: an account has tens of datasets, not thousands, and a workbook wants the whole list. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"brand","in":"query","schema":{"type":"string"},"description":"Narrow to one brand (its id): its connections' tables plus its marketing_daily. `all` lists every brand even when one is selected in the app. A brand id that is not yours answers 404, never an empty list. Omit for everything you own (a key-authenticated call, e.g. Power BI, always lists everything; the signed-in web app and MCP default to the brand selected in the app). The older spelling `client` is still accepted for links minted before 2026-09-22."},{"name":"instances","in":"query","schema":{"type":"string"},"description":"Comma-separated connector instance ids, to narrow further to some of the connections inside that brand. An id that is not yours, or not in the brand, answers 404 rather than a shorter list."}],"responses":{"200":{"description":"Every dataset you own","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"brand":{"type":"string","format":"uuid","nullable":true,"description":"The brand the list was narrowed to, null when it was not"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"slug":{"type":"string","nullable":true,"description":"null for private datasets: a canonical slug is generated for public ones only"},"kind":{"type":"string","enum":["connector","upload","derived","shared"]},"connector":{"type":"string","nullable":true,"description":"The connector that writes this table, null for an upload and for a table shared with you"},"brand":{"type":"string","nullable":true,"description":"The brand this table reports for, null when there is none"},"brand_id":{"type":"string","format":"uuid","nullable":true,"description":"The id of that brand (the value `?brand=` takes), null when `brand` is null"},"shared_by":{"type":"string","nullable":true,"description":"The owner who shared this table with you (kind shared); null on every table you own"},"app":{"type":"string","nullable":true,"description":"The first-party app whose results this derived table holds (for example AI Visibility 360); null on every other kind and on the marketing_daily table"},"app_id":{"type":"string","nullable":true,"description":"The id of that app (for example ai-visibility); null when `app` is null"},"rows":{"type":"integer","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}}}},"query_url":{"type":"string","description":"Absolute URL of the filtered/paginated query endpoint"},"csv_url":{"type":"string","description":"Absolute URL of the streaming CSV export (whole table, no row cap)"}}}}}}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"The requested client is not yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/datasets":{"get":{"operationId":"listAccessibleDatasets","summary":"List datasets accessible to your API key (paginated)","description":"Returns datasets you own, datasets you have been granted access to, and all public datasets. Paginated: default limit 100, max 1000. Use next_offset to fetch the following page (null on the last page). Filter with q (free-text search over title, description, category, keywords, publisher) and mine=true (only datasets you own). Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":100,"minimum":1,"maximum":1000},"description":"Page size (max 1000)"},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0},"description":"Rows to skip; pass the previous response's next_offset"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Free-text search (title, description, category, keywords, publisher); synonym-aware, title matches rank first"},{"name":"mine","in":"query","schema":{"type":"boolean","default":false},"description":"true = only datasets you own (private and public)"}],"responses":{"200":{"description":"One page of accessible datasets","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total datasets matching the filters"},"count":{"type":"integer","description":"Datasets in this page"},"limit":{"type":"integer"},"offset":{"type":"integer"},"page":{"type":"integer"},"pages":{"type":"integer"},"next_offset":{"type":"integer","nullable":true,"description":"Offset of the next page, null when this is the last page"},"has_more":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DatasetMeta"}}}}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}},"post":{"operationId":"createDataset","summary":"Create a dataset","description":"Creates an empty dataset owned by the caller. The table schema is inferred from the FIRST batch of rows appended via POST /datasets/{id}/rows. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`. This endpoint also carries the storage ceiling, so it can refuse with `scope: \"storage_mb\"`. App bundles count toward the same allowance as dataset rows, and the refusal does not clear by waiting.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"is_public":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Created dataset","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Missing title","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/datasets/{id}/rows":{"post":{"operationId":"appendDatasetRows","summary":"Append rows to your dataset","description":"Appends rows to a dataset you own (schema is inferred and created from the first batch). Max 10000 rows per request. Ownership enforced: only your own datasets (404 otherwise). Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`. This endpoint also carries the storage ceiling, so it can refuse with `scope: \"storage_mb\"`. App bundles count toward the same allowance as dataset rows, and the refusal does not clear by waiting.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","items":{"type":"object"},"description":"Row objects; keys of the first batch define the schema. Max 10000 per request."}}}}}},"responses":{"200":{"description":"Insert result","content":{"application/json":{"schema":{"type":"object","properties":{"inserted":{"type":"integer"},"total":{"type":"integer"}}}}}},"400":{"description":"Missing/invalid rows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Not found or not your dataset"}}},"delete":{"operationId":"clearDatasetRows","summary":"Clear all rows of your dataset (keeps schema)","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Delete result","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Not found or not your dataset"}},"description":"Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`."}},"/datasets/{id}":{"get":{"operationId":"getDatasetMeta","summary":"Get metadata for an accessible dataset","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Dataset metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetMeta"}}}},"401":{"description":"Invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Not found or access denied"}},"description":"Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`."},"delete":{"operationId":"deleteDataset","summary":"Delete your dataset","description":"Removes the dataset and its rows. Owner-scoped: a dataset you do not own answers 404, never 403. To empty a dataset while keeping its shape and its id, use DELETE /datasets/{id}/rows instead, which is what a scheduled full replace should do (the id stays stable, so charts and apps pointing at it keep working). Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}}}}},"401":{"description":"Invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Not found or not yours"}}}},"/datasets/{id}/schema":{"get":{"operationId":"getDatasetSchema","summary":"Get schema of an accessible dataset","description":"Returns column names, types, row count, column count, and a `semantics` entry per column saying what it MEANS (kind, definition, unit, currency, time grain, and where the meaning came from). Always call this before queryDataset to know which columns exist, and read `semantics` before combining two columns: autario refuses to combine columns of different kinds. `source_time_col` names the time axis (null when none is declared); filter it with `gte` and `lt` on queryDataset to read only a date range. On a private or derived table the response also carries `lineage`: where the table comes from (connector report, upload, app result, the tables a derived one folds) and what reads it (derived tables, apps, charts, KPIs, the share), cut for the caller. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Dataset schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaResponse"}}}},"401":{"description":"Invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Not found or access denied"}}}},"/datasets/{id}/query":{"get":{"operationId":"queryDataset","summary":"Query rows from a dataset","description":"Fetch filtered, sorted, and paginated rows from a dataset.\nAlways call getDatasetSchema first to know which column names are valid.\n\n**Filter syntax:** `column:op:value`\n- Operators: `eq`, `neq`, `gt`, `lt`, `gte`, `lte`, `like`\n- `like` is case-insensitive and auto-wraps value in %\n- Repeat for multiple filters: `?filters=year:gt:2020&filters=country:eq:Germany`\n- NOTE: this endpoint takes `filters` (plural). The public /data endpoints and the proxy `datasetData` op take `filter` (singular). A mismatched param name is silently ignored and returns unfiltered data.\n\n**Sort syntax:** `column:asc` or `column:desc` Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"fields","in":"query","description":"Comma-separated list of column names to return (default: all columns)","schema":{"type":"string","example":"year,country,gdp_usd"}},{"name":"filters","in":"query","description":"Filter expression: `column:op:value`. Repeatable. This endpoint uses `filters` (plural); the public /data endpoints use `filter` (singular).","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"},"example":["year:gt:2000","country:eq:Germany"]}},{"name":"sort","in":"query","description":"Sort by column: `column:asc` or `column:desc`","schema":{"type":"string","example":"year:desc"}},{"name":"limit","in":"query","description":"Rows per request. The ceiling is the same one the public /data endpoint applies to the same store. For a whole table use GET /datasets/{id}/export, which does not page at all.","schema":{"type":"integer","default":100,"minimum":1,"maximum":50000}},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}},{"name":"overlay","in":"query","description":"Which data (spec 2026-10-28-data-overlay-layer). `source` (default) = exactly what the provider delivered, byte-identical rows to a call without this parameter. `with_overlay` = accepted derived columns, corrections and mappings merged in; each row carries `_row_key` and, when an overlay entry touched it, `_overlay` (original value, reason, who, when). `proposed` (dataset owner only, 403 otherwise) = accepted AND open proposals, every entry with its state. The answer says which in `meta.overlay_mode` (query) or the `X-Autario-Overlay-Mode` header (export).","schema":{"type":"string","enum":["source","with_overlay","proposed"],"default":"source"}}],"responses":{"200":{"description":"Query results with pagination metadata. A dataset created with POST /datasets and not written yet answers total 0 and an empty data array.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"400":{"description":"A column named in fields, filters or sort does not exist (error_code unknown_column), or a filter value does not fit its column (error_code bad_filter_value)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Not found or access denied (also an id that is not a uuid)"},"500":{"description":"The query failed on our side; the body carries request_id"}}}},"/datasets/{id}/export":{"get":{"operationId":"exportDataset","summary":"Download a dataset you can read as CSV","description":"Streams the WHOLE table as `text/csv` with no paging and no row cap, which is what a BI tool wants when the raw table is the point. A table of several thousand rows arrives in one response instead of in a loop over `offset`.\n\nUse GET /datasets/{id}/query instead when you want a filtered slice, selected columns or a server-side aggregate: those keep a refresh fast because the rows never travel.\n\nAn empty dataset answers 204 with no body, rather than a header row that would read as a successful pull of zero rows.\n\nSame ownership rule as every other private read: a dataset that is not yours answers 404, indistinguishable from one that does not exist. Reads of your own data are recorded in your access log. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"overlay","in":"query","description":"Which data (spec 2026-10-28-data-overlay-layer). `source` (default) = exactly what the provider delivered, byte-identical rows to a call without this parameter. `with_overlay` = accepted derived columns, corrections and mappings merged in; each row carries `_row_key` and, when an overlay entry touched it, `_overlay` (original value, reason, who, when). `proposed` (dataset owner only, 403 otherwise) = accepted AND open proposals, every entry with its state. The answer says which in `meta.overlay_mode` (query) or the `X-Autario-Overlay-Mode` header (export).","schema":{"type":"string","enum":["source","with_overlay","proposed"],"default":"source"}}],"responses":{"200":{"description":"The dataset as CSV. In an overlay mode the derived columns follow the source columns, then `_row_key` and `_overlay` (JSON).","content":{"text/csv":{"schema":{"type":"string"}}}},"204":{"description":"The dataset has no rows; no body is sent"},"401":{"description":"Invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Not found or access denied"}}}},"/datasets/{id}/overlays":{"get":{"operationId":"listDatasetOverlays","summary":"List the overlay layer of a dataset","description":"The overlay layer sits ON TOP of a dataset's source rows and never changes them: derived columns (a value per row: topic, group, label), flags (this row looks wrong because ...), cell corrections (the original stays) and mappings (master data: source value -> canonical value for a column). Each entry carries its reason, who wrote it (person, api_key, agent), when, and a state: proposed, accepted, rejected or superseded.\n\nDefault `state=accepted` = the layer every `overlay=with_overlay` read applies; anyone who may read the dataset may list it. Other states (open proposals, history) are the owner's. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"state","in":"query","schema":{"type":"string","enum":["accepted","proposed","rejected","superseded","all"],"default":"accepted"}},{"name":"kind","in":"query","schema":{"type":"string","enum":["column","flag","correction","mapping"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":500,"minimum":1,"maximum":5000}},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"`{ dataset_id, state, counts: {proposed, accepted, rejected, superseded}, data: [{ id, kind, column, state, value, original, reason, by, at, decided_at?, row_key?, source_value? }] }`"},"401":{"description":"Invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"403":{"description":"A state other than accepted, asked by someone who is not the owner"},"404":{"description":"Not found or access denied"}}},"post":{"operationId":"proposeDatasetOverlays","summary":"Propose derived values, flags, corrections or mappings","description":"Writes overlay entries for one dataset you own; the source rows are never touched. Body by `kind`:\n- `column`: `{ kind, column, values: [{ row_key, value, reason? }], reason? }`\n- `flag`: `{ kind, rows: [{ row_key, column?, reason? }], reason? }`\n- `correction`: `{ kind, corrections: [{ row_key, column, value, reason? }], reason? }`\n- `mapping`: `{ kind, column, mappings: [{ source_value, value, reason? }], reason? }`\n\n`row_key` = the `_row_key` a query with `overlay=with_overlay` returned (the producing report's merge key, else a fingerprint of the row). Every entry needs a reason. A write in the browser lands `accepted`; a write with an API key or through MCP lands `proposed` unless the owner marked that key trusted. Up to 5000 entries per call; one bad entry refuses the whole call. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["column","flag","correction","mapping"]},"column":{"type":"string"},"reason":{"type":"string"},"values":{"type":"array","items":{"type":"object"}},"rows":{"type":"array","items":{"type":"object"}},"corrections":{"type":"array","items":{"type":"object"}},"mappings":{"type":"array","items":{"type":"object"}}}}}}},"responses":{"201":{"description":"`{ dataset_id, ids: [..], state: proposed|accepted, count, identity: key|fingerprint, next_step }`"},"400":{"description":"Invalid entry (the sentence names it), or row keys that match no row (`unknown_row_keys`)"},"401":{"description":"Invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"403":{"description":"Not the owner of this dataset"},"404":{"description":"Not found or access denied"}}}},"/datasets/{id}/overlays/decide":{"post":{"operationId":"decideDatasetOverlays","summary":"Accept or reject open proposals, in bulk","description":"`{ ids: [..], decision: accept | reject }`. Only open proposals are decided. Accepting supersedes the accepted entry on the same target. Accepting needs the owner in the browser or an API key the owner marked trusted; rejecting works on any owner credential. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids","decision"],"properties":{"ids":{"type":"array","items":{"type":"integer"}},"decision":{"type":"string","enum":["accept","reject"]}}}}}},"responses":{"200":{"description":"`{ dataset_id, decision, decided, ids, not_open }`"},"400":{"description":"Bad ids or decision"},"401":{"description":"Invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"403":{"description":"Not the owner, or accept on an untrusted key"},"404":{"description":"Not found or access denied"}}}},"/datasets/{id}/overlays/{overlayId}":{"delete":{"operationId":"removeDatasetOverlay","summary":"Remove one overlay entry","description":"Deletes one overlay entry; the source rows are never touched. Removing an accepted entry needs the owner in the browser or a trusted key. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"overlayId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"`{ removed, kind, state }`"},"401":{"description":"Invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"403":{"description":"Not the owner, or an accepted entry on an untrusted key"},"404":{"description":"Not found or access denied"}}}},"/connectors":{"get":{"operationId":"listConnectors","summary":"List your REST connector instances","description":"Returns the caller's own connector instances (user-configured REST API pulls) with status, refresh interval, last run, the queryable dataset_id of the primary hosted table, datasets[] (every dataset the instance materialized; multi-report connectors produce one per report) and a compact `health` (state, data age per dataset, next_step: who acts and how). Connectors are created and configured in the Autario UI (Settings > Connectors); this API never changes them. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"responses":{"200":{"description":"Your connector instances","content":{"application/json":{"schema":{"type":"object","properties":{"connectors":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorInstance"}}}}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/connectors/{id}":{"get":{"operationId":"getConnector","summary":"Get one of your connector instances","description":"Returns a single connector instance (same shape as a listConnectors entry, including datasets[]) with the FULL `health`: per-report outcome (delivered | empty | not_fetched with the reason), schedule, next run, newest data day per table and next_step. Read-only, never starts a run. Ownership enforced: only your own connector instances (404 otherwise). Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Connector instance id from listConnectors"}],"responses":{"200":{"description":"Connector instance","content":{"application/json":{"schema":{"type":"object","properties":{"connector":{"$ref":"#/components/schemas/ConnectorInstance"}}}}}},"401":{"description":"Missing or invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Connector not found or not yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connectors/{id}/refresh":{"post":{"operationId":"refreshConnector","summary":"Refresh a connector's hosted table now","description":"Pulls the connector's source REST API immediately and rewrites the hosted table (deterministic fetch, no server-side LLM). Runs synchronously and returns status (refreshed | failed), the row count, the queryable dataset_id and the finished run's `health`. It does not start a run that cannot help: 409 needs_sign_in (the login is gone; setup_url is where the user signs in again), 409 already_running, 429 too_soon (one run per instance per 10 minutes of any trigger; retry_at + Retry-After). Ownership enforced: only your own connector instances (404 otherwise). Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Connector instance id from listConnectors"}],"responses":{"200":{"description":"Refresh result","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["refreshed","failed"],"description":"failed = the run happened and delivered with problems; health says which reports and why"},"rows":{"type":"integer"},"dataset_id":{"type":"string","format":"uuid","nullable":true},"health":{"$ref":"#/components/schemas/ConnectorHealth"}}}}}},"401":{"description":"Missing or invalid credentials"},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Connector not found or not yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not started: reason needs_sign_in (with setup_url) or already_running; health attached"},"429":{"description":"Not started: reason too_soon, retry_at says when the next run may start; health attached"},"500":{"description":"Server error (database or ownership read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps/marketing-report/report":{"get":{"operationId":"getMarketingReport","summary":"One brand's marketing report across every ad platform and shop","description":"Reads the caller's own derived `marketing_daily` table (one row per brand, channel, account, campaign, day and currency, built by the metric layer) and returns finished arithmetic: spend, conversions, revenue, conversion value, return on ad spend and cost per acquisition for a period, each against the same window shifted by its own rhythm, plus one row per channel, top campaigns by spend and by return on ad spend, a daily series and a data-health line per channel. No server-side LLM and no new ingest. Login or API key required. SCOPE: one brand per call. `brand` picks one (the older spelling `client` is still accepted); omitted means the account's Default brand, which is where every unassigned connector already belongs. A brand that is not the caller's answers 404, never another brand's numbers. DEFINITIONS travel WITH the payload (`definitions`), generated from the same rule that computes each column, so a caller never has to assume what went into a ratio. CURRENCY: money is never converted. A window holding more than one currency answers null for every money field with a `reason` naming them, and `kpis.by_currency` carries one real total per currency instead, which is the case when the channels of one brand report in different currencies. ATTRIBUTION is whatever each ad platform reported under its own setting and is never de-duplicated across channels; shop revenue and analytics revenue are separate rows and must not be added. GAPS: a day nobody reported is absent from `daily` rather than present as a zero, and a ratio with no denominator is null rather than infinite. EMPTY STATES: `state` is one of ok, no_brands, no_connectors, not_built, empty_window, each with a headline, a detail and where to go; none of them means the numbers are zero.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"brand","in":"query","required":false,"description":"Brand id (uuid). Omitted means the account's Default brand. A foreign id answers 404. The older spelling `client` is still accepted.","schema":{"type":"string","format":"uuid"}},{"name":"period","in":"query","required":false,"description":"The window. 'this-week' runs Monday to today and compares to the same weekdays one week earlier; 'last-week' is the previous full Monday to Sunday; 'last-30' ends today; 'custom' needs from and to. An unusable custom pair falls back to last-30 rather than erroring.","schema":{"type":"string","enum":["this-week","last-week","last-30","custom"],"default":"last-30"}},{"name":"from","in":"query","required":false,"description":"Start day (YYYY-MM-DD), with period=custom.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End day (YYYY-MM-DD), with period=custom.","schema":{"type":"string","format":"date"}},{"name":"days","in":"query","required":false,"description":"Shorthand for the last N days ending today. Ignored when period is given.","schema":{"type":"integer"}},{"name":"instances","in":"query","required":false,"description":"Comma-separated connector instance ids, to narrow the report to some of the connections inside the brand (for example one of two Meta ad accounts). Omitted means all of them. An id that is not yours, or not in that brand, answers 404 rather than a quietly shorter report. A channel whose account the platform never publishes cannot be attributed to one connection, so its rows are all kept rather than guessed away.","schema":{"type":"string"}}],"responses":{"200":{"description":"The report. Money carries the currency its source reported and is never converted.","content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","description":"ok | no_brands | no_connectors | not_built | empty_window. Anything but ok carries headline, detail and an action; none of them means zero."},"client":{"type":"object","nullable":true,"description":"The client this report is about: id, name, is_default."},"clients":{"type":"array","description":"Every client of the caller, so a first call without `client` says what could be passed next.","items":{"type":"object"}},"period":{"type":"object","description":"preset, label, from, to, days, and `prior` (the comparison window) plus prior_label saying in words what it is."},"dataset":{"type":"object","nullable":true,"description":"The derived table behind the report: its id, its key, built_at (when it was last rebuilt) and rows_total."},"kpis":{"type":"object","description":"Each of spend, conversions, revenue, conversion_value, roas and cpa as { value, prior, change }, plus `by_currency` with one real total per currency and `reason` when the money was refused."},"channels":{"type":"array","description":"One row per channel with the same metrics, its share_of_spend and its own currency facts.","items":{"type":"object"}},"campaigns":{"type":"object","description":"by_spend and by_roas, each row carrying the spend behind the ratio. No hidden minimum spend is applied."},"daily":{"type":"array","description":"One row per day that actually reported. A missing day is absent, never a zero.","items":{"type":"object"}},"health":{"type":"array","description":"Per channel: last_day, days_behind, currencies and one sentence. Coverage only; no per connector refresh time is claimed, because that fact is not in the table.","items":{"type":"object"}},"definitions":{"type":"array","description":"Every metric's formula and its definition, generated from the same table that computes the column.","items":{"type":"object"}},"honesty":{"type":"array","description":"The rules that hold for every number above.","items":{"type":"string"}}}}}}},"401":{"description":"Login or API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"That client does not belong to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps/llm-costs/report":{"get":{"operationId":"getLlmCostsReport","summary":"Your own LLM spend per provider, model and day","description":"Reads the caller's own openai_usage and anthropic_usage connector tables and returns finished spend arithmetic (no server-side LLM, no new ingest). Login or API key required. SETUP: both connectors authenticate with an ORGANIZATION ADMIN key, not a normal inference key - an Anthropic admin key starts with sk-ant-admin01- (Claude Console, Settings, Admin keys) and OpenAI's is created under Settings, Organization, Admin keys. A project/inference key answers 401/403/404 on the vendors' usage APIs and the connector will hold no rows. COST PRECEDENCE, never mixed: where the vendor DELIVERS cost, that is what is reported (costBasis 'reported', discounts included); otherwise spend is estimated from tokens times public list prices (costBasis 'estimated'), which no real invoice will match exactly. ANCHOR: windows count back from anchorDay, the newest day the provider actually delivered, not from the wall clock - both vendors lag by about a day, so a wall-clock anchor would read $0.00 permanently. anyConnected/anyData distinguish 'not connected' from 'connected but no data yet'; neither is reported as a zero amount. Credits are human input (see /apps/llm-costs/credits) because no vendor exposes a balance API, and the runway is derived from them.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"days","in":"query","required":false,"description":"Window length. One of 7, 30, 90; anything else falls back to 30.","schema":{"type":"integer","enum":[7,30,90],"default":30}},{"name":"include","in":"query","required":false,"description":"Comma-separated extras. 'breakdown' adds spend and tokens per OpenAI project / Anthropic workspace plus tokens per API key. Opt-in, because it costs extra table reads per provider. Cost per API KEY does not exist: neither vendor groups money that way.","schema":{"type":"string","example":"breakdown"}},{"name":"brand","in":"query","required":false,"description":"Brand id (uuid) to report on. Omitted means every usage connection you own.","schema":{"type":"string","format":"uuid"}},{"name":"instances","in":"query","required":false,"description":"Comma-separated connector instance ids, to narrow to some of the usage connections inside that brand (an account with two OpenAI admin keys is the case this exists for). An id that is not yours answers 404.","schema":{"type":"string"}}],"responses":{"200":{"description":"The report. Amounts are USD.","content":{"application/json":{"schema":{"type":"object","properties":{"generatedFor":{"type":"string","description":"Today, as the report saw it."},"anchorDay":{"type":"string","description":"Newest day any connected provider delivered. Every window counts back from HERE."},"windowDays":{"type":"integer"},"anyConnected":{"type":"boolean"},"anyData":{"type":"boolean"},"dataThrough":{"type":"string","nullable":true},"staleDays":{"type":"integer","nullable":true},"totals":{"type":"object","description":"usdWindow / usdLatestDay / usd7d / usd30d plus token sums."},"providers":{"type":"array","description":"One row per provider: connected, state, costBasis (reported|estimated|none), the window amounts, token counts, runway and honesty notes (estimated cost, unpriced models, Anthropic priority-tier spend the cost report leaves out).","items":{"type":"object"}},"models":{"type":"array","description":"Per (provider, model) usage and cost. Anthropic bills per model; OpenAI's cost report carries only line items, so its model rows are estimated.","items":{"type":"object"}},"breakdown":{"type":"object","description":"Only with include=breakdown. Per project/workspace and per API key, using the vendors' own words for the buckets."},"daily":{"type":"array","description":"Per-day totals with a per-provider split.","items":{"type":"object"}}}}}}},"401":{"description":"Login or API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps/llm-costs/credits":{"get":{"operationId":"listLlmCredits","summary":"Your recorded prepaid LLM top-ups","description":"Lists the caller's own credit entries plus known_providers, the closed provider vocabulary a credit may be booked against (derived from the usage connectors that ship, so today: anthropic, openai). Credits are HUMAN INPUT: no AI vendor exposes a credit-balance API, so the app asks. They are what turns spend into a runway in /apps/llm-costs/report. Ownership is enforced in SQL, so a caller can only ever see their own rows.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"responses":{"200":{"description":"Your credits, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"provider":{"type":"string","example":"anthropic"},"amount_usd":{"type":"number"},"note":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"known_providers":{"type":"array","items":{"type":"string"},"description":"The only accepted provider values."}}}}}},"401":{"description":"Login or API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createLlmCredit","summary":"Record one prepaid LLM top-up","description":"Books a top-up against one of known_providers. amount_usd must be a non-zero number; a NEGATIVE amount is allowed on purpose, because it is how a mistyped entry is corrected without deleting history. created_at is optional and defaults to now. An unknown provider answers 400 naming the accepted values - free text is refused so a second spelling of a vendor can never split a total.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","amount_usd"],"properties":{"provider":{"type":"string","example":"openai","description":"Must be one of known_providers."},"amount_usd":{"type":"number","example":100,"description":"Non-zero. Negative corrects an earlier entry."},"note":{"type":"string","description":"Free text, truncated at 500 chars."},"created_at":{"type":"string","format":"date-time","description":"When the top-up happened. Defaults to now."}}}}}},"responses":{"201":{"description":"The stored credit","content":{"application/json":{"schema":{"type":"object","properties":{"credit":{"type":"object"}}}}}},"400":{"description":"Unknown provider or a zero/non-numeric amount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Login or API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps/llm-costs/credits/{id}":{"delete":{"operationId":"deleteLlmCredit","summary":"Delete one of your credit entries","description":"Removes a mistyped entry. A row belonging to someone else answers the SAME 404 as a row that does not exist, so the endpoint never confirms that an id exists for another account.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer"}}}}}},"400":{"description":"Non-numeric id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Login or API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also the answer for a row that is not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps/llm-costs/budgets":{"get":{"operationId":"listLlmBudgets","summary":"Your monthly spend budget per provider","description":"Lists the caller's own monthly budget per provider. A budget nobody set is ABSENT, never zero: the report then prints the month's spend without a progress bar, because a ceiling nobody chose is not a fact. Ownership is enforced in SQL.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"responses":{"200":{"description":"Your budgets.","content":{"application/json":{"schema":{"type":"object","properties":{"budgets":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"monthly_usd":{"type":"number"}}}}}}}}},"401":{"description":"Login or API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setLlmBudget","summary":"Set the monthly budget for one provider","description":"Upserts one row. provider must be one of the report's known providers; monthly_usd must be a positive number. Setting a budget never changes a credit and never changes an amount already spent, it only gives the month tile a ceiling to draw against.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","monthly_usd"],"properties":{"provider":{"type":"string","example":"openai"},"monthly_usd":{"type":"number","example":120}}}}}},"responses":{"200":{"description":"The stored budget","content":{"application/json":{"schema":{"type":"object","properties":{"budget":{"type":"object"}}}}}},"400":{"description":"Unknown provider or a non-positive amount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Login or API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/apps/llm-costs/budgets/{provider}":{"delete":{"operationId":"deleteLlmBudget","summary":"Remove the budget for one provider","description":"Deletes the row, which puts the month tile back to printing the spend alone. A provider with no budget answers the SAME 404 as one that is not yours.","tags":["Private"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer"}}}}}},"401":{"description":"Login or API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (also the answer for a row that is not yours)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/apps":{"get":{"operationId":"listPublicApps","summary":"List the public data-app catalog","description":"Returns all listed apps (id, name, tagline, route, publisher, shelf, shelf_label, category, image_url, data_scope). `shelf` is the shelf id from the one registry that orders the connector catalogue and the app store alike; `shelf_label` is its user-facing name, and `category` carries that same label (kept for one release, it held a free-text string before 2026-09-20). data_scope is 'private' (the app works on the caller's own connected data, e.g. Search Console) or 'public' (the app runs on public autario datasets only). With ?mine=true and authentication each row additionally carries connected (the caller has data behind the app), activated (explicit toggle on), deactivated (explicit opt-out; a connected app with deactivated=true does not count as one of the caller's apps) and providers (the connector providers the app declares; empty = it works without a connection). No authentication required for the plain catalog. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Apps"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]},{}],"parameters":[{"name":"mine","in":"query","schema":{"type":"boolean","default":false},"description":"true (with auth) = add a connected flag per app"}],"responses":{"200":{"description":"The app catalog","content":{"application/json":{"schema":{"type":"object","properties":{"apps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string","nullable":true},"route":{"type":"string","nullable":true},"publisher":{"type":"string","nullable":true},"shelf":{"type":"string","description":"The id of the shelf this sits on, from the one shelf registry that orders the connector catalogue and the app store alike (search, analytics, social, ads, commerce, financial_markets, banking_accounting, crm, productivity, developer, ai, public_data, other). Added 2026-09-20; an unknown value is never returned."},"shelf_label":{"type":"string","description":"The shelf's user-facing name."},"category":{"type":"string","nullable":true,"description":"Deprecated alias of shelf_label, kept for one release."},"image_url":{"type":"string","nullable":true},"data_scope":{"type":"string","enum":["private","public"],"description":"private = works on the caller's own connected data (a declared connector provider, or a declared dataset that is a private asset); public = public datasets only"},"connected":{"type":"boolean","description":"Only present with ?mine=true + auth"},"own":{"type":"boolean","description":"Only present with ?mine=true + auth, and only as true: the caller built this app"},"preview":{"type":"boolean","description":"Only present for the curator account: the app is unlisted (private preview) but already has a live route"}}}}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/apps/{id}/context":{"get":{"operationId":"getAppContext","summary":"Get an app's data map (manifest + your connected data)","description":"The app-first navigation door for agents: returns the app's manifest (consumed datasets/ops and declared connector providers) plus, when the caller authenticates with an account API key, the caller's OWN data behind the app: connector-instance tables (per-operation table with column list, row count, backing dataset_id and last refresh), saved artifacts, and ready-to-run query examples on existing endpoints. Secrets and credentials are never included (server-side redaction). Without auth the response is the public manifest view. 404 if the app id is unknown. MCP equivalents: list_apps + get_app_context. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Apps"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"App id from GET /public/apps, e.g. audience-360"}],"responses":{"200":{"description":"App context","content":{"application/json":{"schema":{"type":"object","properties":{"app":{"type":"object","description":"id, name, tagline, route, category, publisher, tier, status, source_url"},"consumed_datasets":{"type":"array","items":{"type":"object"},"description":"Manifest entries; an entry may declare providers:[connector provider keys], plus optional:true + unlocks:'benefit copy' for sources the app works without but which unlock more sections"},"providers":{"type":"array","items":{"type":"string"}},"authenticated":{"type":"boolean"},"connected":{"type":"boolean","description":"Only with auth: the caller has instances or artifacts behind this app"},"your_data":{"type":"object","description":"Only with auth: { instances: [{ provider, instance, status, last_run_at, settings (redacted), tables: [{ op, table, dataset_id, dataset_slug, row_count, columns }] }], artifacts: [{ slug, type, title, visibility, updated_at }] }"},"query_examples":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"url":{"type":"string"}}}},"hints":{"type":"array","items":{"type":"string"}}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/apps/my/workspace":{"get":{"operationId":"getMyWorkspace","summary":"Your app workspace in one call","description":"Every app the caller built, activated or connected, each with its providers, connector-backed tables (dataset id/slug, row count, last refresh), saved artifact list and one ready-to-run query example. The aggregate an agent loads FIRST when the user references 'my <app>' - it guarantees the agent reasons over the same datasets and saved views the user sees. Auth required (401 without). MCP mirror: get_my_workspace. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Apps"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"responses":{"200":{"description":"Workspace aggregate","content":{"application/json":{"schema":{"type":"object","properties":{"my_apps":{"type":"integer"},"catalog_apps":{"type":"integer"},"note":{"type":"string","description":"Present when apps were omitted by the cap"},"marketing_daily":{"type":"array","description":"One derived marketing_daily dataset per client (spend, impressions, clicks, conversions, conversion value, orders, revenue and the derived roas/cpa/ctr/cpc, one row per client, channel, account, campaign, day and currency). Present only when the caller has one. Items: { client_id, client, dataset_id, row_count, last_refresh }","items":{"type":"object"}},"app_results":{"type":"array","description":"The first-party apps' results as the caller's own derived datasets (AI Visibility 360 per brand: visibility_scores, visibility_answers, visibility_prompts). Present only when the caller has one. Items: { app_id, app, kind, brand_id, brand, dataset_id, title, row_count, last_refresh, origin }","items":{"type":"object"}},"apps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string"},"route":{"type":"string"},"activated":{"type":"boolean"},"connected":{"type":"boolean"},"providers":{"type":"array","items":{"type":"string"}},"tables":{"type":"array","items":{"type":"object","description":"{ op, dataset_id, dataset_slug, row_count, last_refresh }"}},"artifacts":{"type":"array","items":{"type":"object","description":"{ slug, type, title, visibility, updated_at }"}},"query_example":{"type":"object","description":"{ description, method, url } or null"}}}}}}}}},"401":{"description":"Authentication required. Carries error_code:'login_required' + a hint naming the x-api-key/x-api-secret headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthRefusal"}}}},"402":{"$ref":"#/components/responses/PlanLimit"}}}},"/public/apps/{id}/artifacts/{slug}":{"get":{"operationId":"getAppArtifact","summary":"Read one saved artifact (full spec + data)","description":"The exact saved view state behind an app artifact: spec (the app-specific configuration - report config, chart spec, board) plus any inline data blob. Visibility gate: the owner reads private artifacts; everyone reads public and unlisted ones; a foreign private artifact answers 404 (existence is not leaked). MCP mirror: get_app_artifact (token-bounded). Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Apps"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"App id the artifact belongs to"},{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Artifact slug (from /apps/{id}/context your_data.artifacts or /apps/my/workspace)"}],"responses":{"200":{"description":"Artifact","content":{"application/json":{"schema":{"type":"object","properties":{"artifact":{"type":"object","description":"{ slug, app_id, type, title, visibility, yours, spec, data, forked_from, created_at, updated_at }"}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"Not found or not visible to the caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/apps/{id}/artifacts":{"post":{"operationId":"createAppArtifact","summary":"Save an artifact into an app","description":"Creates an artifact owned by YOU inside an app you can open (your own, or a public/unlisted one). `type` is your own label for the kind of thing it is, `spec` and `data` are free-form JSON. Read it back with GET /public/apps/{id}/artifacts/{slug}. An app you cannot open answers 404, the same as an unknown id. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Apps"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","example":"chart","description":"Your own label for the kind of artifact."},"title":{"type":"string"},"spec":{"type":"object","description":"The saved view or configuration."},"data":{"type":"object","description":"Optional inline data."},"visibility":{"type":"string","enum":["private","unlisted","public"],"default":"private"}}}}}},"responses":{"200":{"description":"The stored artifact (a receipt, never the spec/data back)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppArtifactRef"}}}},"400":{"description":"bad_params: params.type required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"not_found: unknown app, or an app you may not open","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/apps/{id}/artifacts/{artifactId}":{"patch":{"operationId":"updateAppArtifact","summary":"Update an artifact you own","description":"Patches title, spec, data or visibility of an artifact YOU own inside this app. Anything else in the body is ignored. Unknown id, an artifact belonging to a different app, and an artifact owned by someone else all answer the same 404. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Apps"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifactId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"spec":{"type":"object"},"data":{"type":"object"},"visibility":{"type":"string","enum":["private","unlisted","public"]}}}}}},"responses":{"200":{"description":"The stored artifact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppArtifactRef"}}}},"400":{"description":"bad_params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"not_found: unknown app or artifact, or one you do not own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/apps/{id}/activate":{"post":{"operationId":"activateApp","summary":"Mark an app as one of your apps","description":"Stores the explicit activation (user intent) for the calling account. 'My apps' reads (GET /public/apps?mine=true, /public/apps/my/workspace, MCP get_my_workspace) return the UNION of explicitly activated and derived connected apps. Idempotent. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Apps"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Activated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"activated":{"type":"boolean"}}}}}},"401":{"description":"Authentication required. Carries error_code:'login_required' + a hint naming the x-api-key/x-api-secret headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthRefusal"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deactivateApp","summary":"Remove an app from your apps","description":"Deletes the explicit activation. Idempotent; a connected app (with real data behind it) still counts as yours via the derived state - deactivation never hides real data. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Apps"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deactivated","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"activated":{"type":"boolean"}}}}}},"401":{"description":"Authentication required. Carries error_code:'login_required' + a hint naming the x-api-key/x-api-secret headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthRefusal"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/apps/{id}/manifest":{"get":{"operationId":"getAppManifest","summary":"Get an app's manifest","description":"Returns the app's submission manifest (what it consumes, where its bundle/entry lives, version, OSS source, lifecycle status) plus display facets. Public - the contract is discoverable so a developer can inspect an existing app's manifest as a template. 404 if the app id is unknown. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`.","tags":["Apps"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"App manifest","content":{"application/json":{"schema":{"type":"object","properties":{"manifest":{"$ref":"#/components/schemas/AppManifest"},"data_scope":{"type":"string","enum":["private","public"],"description":"private = the app reads a connector provider or a private dataset, so a signed-out visitor sees no rows"}}}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"upsertAppManifest","summary":"Register or update an app's manifest","description":"Updates the manifest of an app you own (the id comes from the path). Requires an authenticated caller (account API key or cookie); 401 without. tier is required, tier-2 apps must declare entry_url. 400 on validation failure. An id with no app answers 409 `create_with_post`: create apps with POST /developer/apps, which mints the id. First-party seeds are the only rows created under a fixed id. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`. This endpoint also carries the private-app ceiling, so it can refuse with `scope: \"private_apps\"`. That refusal does not clear by waiting: publish an app, delete one, or lift the plan.","tags":["Apps"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tier"],"properties":{"name":{"type":"string","description":"Display name, free text up to 80 characters; optional on update (a rename never changes the id)"},"tier":{"type":"integer","enum":[1,2],"description":"1 = declarative, 2 = sandboxed"},"consumed_datasets":{"type":"array","items":{"type":"string"},"description":"Datasets/ops the app reads (default []). Entries may declare providers:[connector provider keys]; optional:true + unlocks:'benefit copy' mark sources the app works without but which unlock more sections"},"entry_url":{"type":"string","description":"Bundle/iframe entry; REQUIRED when tier=2"},"version":{"type":"string"},"source_url":{"type":"string","description":"OSS repo"},"status":{"type":"string","enum":["draft","submitted","approved","published"],"default":"published"}}}}}},"responses":{"200":{"description":"Stored manifest","content":{"application/json":{"schema":{"type":"object","properties":{"manifest":{"$ref":"#/components/schemas/AppManifest"}}}}}},"400":{"description":"Manifest validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required. Carries error_code:'login_required' + a hint naming the x-api-key/x-api-secret headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthRefusal"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"403":{"description":"Only the app owner may update an existing app / upload its bundle. Carries error_code:'not_owner'.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthRefusal"}}}},"409":{"description":"No app has this id. error_code:'create_with_post': create the app with POST /developer/apps, which mints its id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/apps/{id}/bundle":{"post":{"operationId":"uploadAppBundle","summary":"Upload an app's bundle bytes","description":"Stores the bundle payload for an app (one row per app_id + version) and computes a sha256 digest. Requires an authenticated caller; 401 without. Same validator as POST /developer/apps/{id}/bundle: `content` is one text entry document (html or javascript, at most 512 KB, utf8 or base64 via `encoding`), or `files` / `zip` = index.html plus its JS, CSS, images and pages (2 MB in total, relative paths, allowlisted types); a `storage_ref`-only row is also allowed. Returns the stored metadata (NOT the bytes). 400 `bad_bundle` for an oversized, wrong-type or path-escaping payload, 400 for an unknown app id or missing payload. Can answer 402: every request authenticated with an API key counts against your account's daily call budget (`reason: \"plan_limit\"`, `scope: \"api_calls_day\"`). The budget is per ACCOUNT, not per key, and every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope: account` so you can see it coming instead of discovering it. An anonymous request is not counted here and is covered by the per-IP limiter instead, which reports the same three headers with `X-RateLimit-Scope: ip`. This endpoint also carries the storage ceiling, so it can refuse with `scope: \"storage_mb\"`. App bundles count toward the same allowance as dataset rows, and the refusal does not clear by waiting.","tags":["Apps"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Bundle payload (utf8 or base64). Optional if storage_ref is given."},"encoding":{"type":"string","enum":["utf8","base64"],"default":"utf8"},"content_type":{"type":"string","example":"application/javascript"},"version":{"type":"string","example":"1.0.0"},"storage_ref":{"type":"string","description":"Future CDN reference; allowed instead of inline content"}}}}}},"responses":{"200":{"description":"Stored bundle metadata","content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"version":{"type":"string","nullable":true},"sha256":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"storage_ref":{"type":"string","nullable":true},"size":{"type":"integer","description":"Bundle byte length (0 for a storage_ref-only row)"}}}}}},"400":{"description":"Unknown app id or missing payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required. Carries error_code:'login_required' + a hint naming the x-api-key/x-api-secret headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthRefusal"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"403":{"description":"Only the app owner may update an existing app / upload its bundle. Carries error_code:'not_owner'.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthRefusal"}}}}}}},"/developer/apps":{"get":{"operationId":"listMyDevApps","summary":"List your own apps","description":"Lists the apps YOU own, newest first, each with its lifecycle fields and the LATEST review verdict (so the dashboard shows submitted / approved / rejected without opening detail). Auth: session cookie or account API key. Never returns another owner's app; an account with no apps gets an empty array, not a 404.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"responses":{"200":{"description":"Your apps","content":{"application/json":{"schema":{"type":"object","properties":{"apps":{"type":"array","items":{"$ref":"#/components/schemas/DevAppSummary"}},"limits":{"type":"object","properties":{"declared_datasets":{"type":"integer","nullable":true,"description":"How many datasets ONE app may declare on your plan (plans.json appDatasets). Null = no cap."}}}}}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createMyDevApp","summary":"Register an app (name plus entry in one request)","description":"Registers a new app in ONE request. autario MINTS the app id: the name lowercased with non-alphanumerics collapsed to single hyphens (at most 44 chars, `app` when fewer than three usable characters survive), then a hyphen and 5 random lowercase base32 characters, e.g. `dashboard-k3x9q`. Any number of people may give an app the same name, nobody can claim a plain word, no id can be guessed from another, and a rename never changes the id. The name itself is free text, 1 to 80 characters. You never invent an id, and this is the only door that creates one.\n\nThe entry lands in the same call. `entry_kind: 'url'` needs an `https://` `entry_url` where the app runs. `entry_kind: 'upload'` needs the bundle itself: `content`, one text entry document (text/html, text/javascript or application/javascript, at most 512 KB decoded, no NUL bytes), or `files` / `zip`, index.html plus its JS, CSS, images and pages (2 MB in total); its stored entry_url becomes `index.html`.\n\nThe created app is tier 2 (sandboxed), `visibility: 'private'`, `listed: false`, `status: 'submitted'`. Private-by-default means only YOU can open it: the sandbox frame and bridge refuse everyone else with a 404. Nothing in v1 flips it public.\n\nRefusals: 400 `bad_name` (empty or longer than 80 characters), 400 `bad_entry` (no https entry url), 400 `bad_bundle` (empty, oversized, wrong type, or binary payload), 400 `bad_manifest` (manifest validation), 503 `id_unavailable` (25 random draws all taken, practically never). This endpoint also carries the private-app ceiling, so it can refuse with `scope: \"private_apps\"`. That refusal does not clear by waiting: publish an app, delete one, or lift the plan.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Display name. The app id is derived from it; needs at least three letters or digits.","example":"Sparkline Demo"},"tagline":{"type":"string","description":"One-line description, trimmed and capped at 200 chars."},"entry_kind":{"type":"string","enum":["url","upload"],"default":"url"},"entry_url":{"type":"string","description":"REQUIRED when entry_kind is 'url'. Must start with https://.","example":"https://example.com/my-app"},"content":{"type":"string","description":"The entry document's bytes when entry_kind is 'upload' (or give files / zip)."},"encoding":{"type":"string","enum":["utf8","base64"],"default":"utf8"},"content_type":{"type":"string","enum":["text/html","text/javascript","application/javascript"],"default":"text/html"},"files":{"type":"array","description":"A multi-file bundle: index.html plus the files it loads by relative path (js, mjs, css, json, svg, png, jpg, webp, woff2, further html pages). Max 50 files, 1 MB each, 2 MB in total, relative paths without \"..\". `content` next to it is index.html.","items":{"type":"object","required":["path","content"],"properties":{"path":{"type":"string","example":"js/app.js"},"content":{"type":"string"},"encoding":{"type":"string","enum":["utf8","base64"],"default":"utf8"}}}},"zip":{"type":"string","format":"byte","description":"The same bundle as a base64 ZIP (index.html at its top level or inside one folder). Not together with content or files."},"source_url":{"type":"string","description":"Optional OSS repository."},"shelf":{"type":"string","description":"The app store shelf the app sits on, one shelf id an app may pick (search, analytics, social, ads, commerce, financial_markets, banking_accounting, crm, productivity, developer, ai, public_data). Optional while the app is private; a publish to unlisted or public answers 422 shelf_required until it has one. Any other value answers 422 bad_shelf with allowed[]. Omitted on update keeps the current shelf."}}}}}},"responses":{"201":{"description":"Created app (its stored manifest). An upload also carries `references`: the dataset ids its bytes reference.","content":{"application/json":{"schema":{"type":"object","properties":{"manifest":{"$ref":"#/components/schemas/AppManifest"},"references":{"$ref":"#/components/schemas/DatasetReferences"}}}}}},"400":{"description":"bad_name, bad_entry, bad_bundle or bad_manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"422":{"description":"bad_shelf: shelf is not an id an app may pick; allowed[] lists them. Nothing was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"id_unavailable: 25 random id draws were all taken (practically never); try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developer/bundle/parse":{"post":{"operationId":"parseMyDevBundle","summary":"Check a bundle and list the datasets it references","description":"Runs the same validator as the create and upload doors over a bundle (`content`, `files` or `zip`) and answers which dataset ids it references, storing nothing. A bundle references a dataset when it calls autario.js anywhere and writes the id as a string literal (`autario.query('<id>')`, or a constant passed to it). Whether an id is yours is not judged here; the create door refuses a stranger's id. How many datasets one app may declare is a plan limit (402 plan_limit scope app_datasets at create and manifest update, `limits.declared_datasets` on GET /developer/apps).","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"One entry document (or index.html when files are given)."},"encoding":{"type":"string","enum":["utf8","base64"],"default":"utf8"},"content_type":{"type":"string","enum":["text/html","text/javascript","application/javascript"],"default":"text/html"},"files":{"type":"array","items":{"type":"object","required":["path","content"],"properties":{"path":{"type":"string"},"content":{"type":"string"},"encoding":{"type":"string","enum":["utf8","base64"]}}}},"zip":{"type":"string","format":"byte","description":"The bundle as a base64 ZIP."}}}}}},"responses":{"200":{"description":"The bundle is valid; what it references","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"integer","description":"Files in the bundle, index.html included."},"references":{"$ref":"#/components/schemas/DatasetReferences"}}}}}},"400":{"description":"bad_bundle: the same refusal the upload doors give","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developer/apps/{id}":{"get":{"operationId":"getMyDevApp","summary":"Your app's detail (manifest, bundle metadata, reviews)","description":"Owner-scoped detail for one of YOUR apps: the full manifest, the latest bundle's METADATA (never the bytes, read those back through GET /sandbox/{appId}/frame), and up to 20 review verdicts newest first (the fix-list after a failed pass). An app you do not own answers 404, the same as an unknown id.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"App detail","content":{"application/json":{"schema":{"type":"object","properties":{"manifest":{"$ref":"#/components/schemas/AppManifest"},"bundle":{"type":"object","nullable":true,"description":"Latest bundle metadata, null when nothing was uploaded yet.","properties":{"version":{"type":"string","nullable":true},"sha256":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"storage_ref":{"type":"string","nullable":true},"size":{"type":"integer","description":"Stored byte length"},"created_at":{"type":"string","format":"date-time"}}},"reviews":{"type":"array","description":"Review history, newest first (max 20).","items":{"type":"object","properties":{"verdict":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"},"nullable":true},"model":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: unknown app OR an app you do not own (the two are deliberately one answer)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteMyDevApp","summary":"Delete your own app","description":"Permanently removes one of YOUR apps and everything hanging off it (proxy tokens, bundles, reviews, installations, artifacts, activations) in one transaction. This is a real delete because the row is your own private app: in no catalog, at no public URL, referenced by no chart, article or sitemap entry. A first-party app is unreachable through this door (owner_id NULL never matches a user id) and answers 404, as does another owner's app.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: unknown app OR an app you do not own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developer/apps/{id}/manifest":{"put":{"operationId":"updateMyDevAppManifest","summary":"Save your app's manifest","description":"Owner-gated manifest write. An existing row must already be yours (404 otherwise); an id with no app answers 409 `create_with_post`, because only POST /developer/apps creates an app and gives it its id. Editing a manifest sends the app back to status 'submitted' for the automated code review, and it keeps RUNNING and keeps whatever visibility you gave it. `visibility` is NOT writable here, an edit must never change who may open an app: publish with PATCH /developer/apps/{id}/visibility. Create an app with POST /developer/apps (it mints the id and takes the entry in the same call). This endpoint also carries the private-app ceiling, so it can refuse with `scope: \"private_apps\"`. That refusal does not clear by waiting: publish an app, delete one, or lift the plan.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tier"],"properties":{"name":{"type":"string","description":"Required on first registration; omitted on update keeps the stored name"},"tier":{"type":"integer","enum":[1,2],"description":"1 = declarative, 2 = sandboxed"},"consumed_datasets":{"type":"array","items":{"type":"string"},"description":"Datasets/ops the app reads (default []). This is ALSO the sandbox bridge's scope: an op the manifest did not declare is refused at runtime."},"entry_url":{"type":"string","description":"Bundle/iframe entry; REQUIRED when tier=2"},"version":{"type":"string"},"source_url":{"type":"string","description":"OSS repo"},"status":{"type":"string","enum":["draft","submitted","approved","published"],"description":"Accepted but overridden to 'submitted' for any owner-submitted app"},"tagline":{"type":"string","description":"One-line description; trimmed, capped at 200 chars"},"shelf":{"type":"string","description":"The app store shelf the app sits on, one shelf id an app may pick (search, analytics, social, ads, commerce, financial_markets, banking_accounting, crm, productivity, developer, ai, public_data). Optional while the app is private; a publish to unlisted or public answers 422 shelf_required until it has one. Any other value answers 422 bad_shelf with allowed[]. Omitted on update keeps the current shelf."}}}}}},"responses":{"200":{"description":"Stored manifest","content":{"application/json":{"schema":{"type":"object","properties":{"manifest":{"$ref":"#/components/schemas/AppManifest"}}}}}},"400":{"description":"bad_manifest: validation failed (missing name/tier, tier-2 without entry_url, non-array consumed_datasets, bad status)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"not_found: the app exists but is not yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"create_with_post: no app has this id; create it with POST /developer/apps, which mints the id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"bad_shelf: shelf is not an id an app may pick; allowed[] lists them. Nothing was written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developer/apps/{id}/bundle":{"post":{"operationId":"uploadMyDevAppBundle","summary":"Upload your app's bundle bytes","description":"Owner-gated bundle upload for an app that already exists. The payload is one text entry document (`content`: text/html, text/javascript or application/javascript, at most 512 KB decoded, no NUL bytes) or a multi-file bundle (`files` or `zip`: index.html plus its JS, CSS, images and pages, served next to it in the sandbox). Re-uploading the same version replaces the whole bundle in place. Returns the stored metadata, never the bytes. A storage_ref-only row (future CDN path) carries no bytes and skips the byte checks. This endpoint also carries the storage ceiling, so it can refuse with `scope: \"storage_mb\"`. App bundles count toward the same allowance as dataset rows, and the refusal does not clear by waiting.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Entry document bytes (index.html when files are given). Optional if storage_ref is given."},"encoding":{"type":"string","enum":["utf8","base64"],"default":"utf8"},"content_type":{"type":"string","enum":["text/html","text/javascript","application/javascript"],"default":"text/html"},"files":{"type":"array","description":"A multi-file bundle: index.html plus the files it loads by relative path (js, mjs, css, json, svg, png, jpg, webp, woff2, further html pages). Max 50 files, 1 MB each, 2 MB in total, relative paths without \"..\". `content` next to it is index.html.","items":{"type":"object","required":["path","content"],"properties":{"path":{"type":"string","example":"js/app.js"},"content":{"type":"string"},"encoding":{"type":"string","enum":["utf8","base64"],"default":"utf8"}}}},"zip":{"type":"string","format":"byte","description":"The same bundle as a base64 ZIP (index.html at its top level or inside one folder). Not together with content or files."},"version":{"type":"string","example":"1.0.0"},"storage_ref":{"type":"string","description":"Future CDN reference; allowed instead of inline content"}}}}}},"responses":{"200":{"description":"Stored bundle metadata","content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"version":{"type":"string","nullable":true},"sha256":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"storage_ref":{"type":"string","nullable":true},"size":{"type":"integer","description":"Bytes of the entry document."},"files":{"type":"integer","description":"Only on a multi-file bundle: the number of files, index.html included."},"total_size":{"type":"integer","description":"Only on a multi-file bundle: the bytes of all files."},"references":{"$ref":"#/components/schemas/DatasetReferences"}}}}}},"400":{"description":"bad_bundle: empty, oversized, unsupported type, binary, or no payload at all","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/PlanLimit"},"404":{"description":"not_found: unknown app OR an app you do not own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developer/apps/{id}/visibility":{"patch":{"operationId":"setMyDevAppVisibility","summary":"Publish or unpublish your app","description":"Moves an app YOU own between three states. Publishing (unlisted or public) needs a paid plan: on Free the answer is 402 `plan_required` (feature `app_publish`); going back to private is never refused.\n\nEvery publish runs a deterministic content check first: an external script, an iframe, a form posting to another host, a meta refresh, an advertising or affiliate link, hidden text, or text aimed at AI agents in the name, tagline or manifest answers 422 `content_rejected` with `rejections[]` (rule, where, line). Both `unlisted` and `public` then pass ONE AI content review per content version (text and code), synchronously, and a `public` listing needs the app hosted on autario (400 `needs_bundle` otherwise): 422 `review_blocked` with `reasons[]`, or 503 `review_unavailable` (retry later, nothing changed). The same content is never reviewed twice.\n\n`private` (the state every app is created in) means only you can open it, at /developer/apps/{id}/run. `unlisted` means anyone holding the link https://autario.com/sandbox/{id} can open it and it is in no catalog. `public` means the same link plus a tile in the app store on the shelf the app names (set `shelf` on the manifest first, otherwise 422 `shelf_required`), credited to your account handle.\n\nA published app is deliberately NOT search-engine indexed. Indexing is autario's decision, not the builder's, because the sitemap is a contract autario signs. `indexable` and `takedown_reason` are therefore CURATOR-only fields on this same route; an ordinary caller sending either gets 403 `curator_only`, and a curator flipping `indexable` on an app without a tagline gets 400 `needs_tagline`.\n\nIf autario has taken the app down, `takedown_reason` is set, the app is pinned to private, and this endpoint answers 403 `app_taken_down` with the reason.\n\nReturns the same object as GET /developer/apps/{id}/preview, so one shape answers both calls.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"visibility":{"type":"string","enum":["private","unlisted","public"],"description":"Who may open the app."},"indexable":{"type":"boolean","description":"CURATOR ONLY. Whether the app's page may enter the sitemap and be indexed."},"takedown_reason":{"type":"string","nullable":true,"description":"CURATOR ONLY. Non-null takes the app down and pins it private; null clears it."}}}}}},"responses":{"200":{"description":"The app's lifecycle state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppLifecycle"}}}},"400":{"description":"bad_visibility (not one of the three states) or needs_tagline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"curator_only (you sent a curator field) or app_taken_down (autario pulled the app; the body carries takedown_reason)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: unknown app OR an app you do not own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"shelf_required (unlisted or public needs a shelf: set shelf on the manifest; allowed[] lists the ids), content_rejected (rejections[]) or review_blocked (reasons[])","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developer/apps/{id}/preview":{"get":{"operationId":"getMyDevAppPreview","summary":"Where to open your app, and what is left to do","description":"The preview URL as a contract instead of a guess: preview_url is the private page where only you can run the app (never indexed), public_url is the shareable link once you publish and null before that, and next_step is one sentence naming the next call to make. Use it after creating an app to hand a human something to click, and before publishing to see what is missing.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The app's lifecycle state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppLifecycle"}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: unknown app OR an app you do not own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developer/tokens":{"get":{"operationId":"listMyDevTokens","summary":"List your scoped app-tokens","description":"Lists the tokens YOU own, newest first. The SECRET is never returned by this endpoint and is not retrievable at all: it is shown exactly once, at mint time, by POST /proxy/token. What comes back is id, name, public key, scope and created_at.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"responses":{"200":{"description":"Your tokens","content":{"application/json":{"schema":{"type":"object","properties":{"tokens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"key":{"type":"string","description":"Public token key (the x-api-key half)"},"scope":{"type":"object","description":"{ ops:[...], datasets?:[uuid], app_id? }","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developer/tokens/{id}":{"delete":{"operationId":"revokeMyDevToken","summary":"Revoke one of your tokens","description":"Revokes a token YOU own. The owner predicate is part of the delete itself, so a token id belonging to someone else matches zero rows and answers 404. Revocation is immediate and final; mint a new token with POST /proxy/token.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: unknown token OR a token you do not own","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developer/profile":{"get":{"operationId":"getMyDeveloperProfile","summary":"Your developer page settings","description":"Your handle, display name, bio and links for the public page /developers/{handle}, plus whether it is earned (one published app or one public dataset) and the two counts behind that.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"responses":{"200":{"description":"{ profile: { handle, url, display_name, bio, website_url, github_url, x_url, linkedin_url, apps_published, datasets_public, earned, status } }"},"401":{"description":"Not signed in"}}},"put":{"operationId":"putMyDeveloperProfile","summary":"Edit your developer page","description":"Partial update: only the keys you send change. `handle` (3 to 30 lowercase letters, digits, single hyphens) is set ONCE and then stays, so links to the page never break (409 handle_locked on a change, 409 handle_taken, 422 bad_handle). Links must be public http(s) addresses; github_url, x_url and linkedin_url must be on their own network. Empty string clears a field.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string"},"display_name":{"type":"string","maxLength":60},"bio":{"type":"string","maxLength":280},"website_url":{"type":"string"},"github_url":{"type":"string"},"x_url":{"type":"string"},"linkedin_url":{"type":"string"}}}}}},"responses":{"200":{"description":"{ profile }"},"401":{"description":"Not signed in"},"409":{"description":"handle_locked or handle_taken","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"bad_profile or bad_handle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developer/usage":{"get":{"operationId":"getMyDevUsage","summary":"Your apps' access meter","description":"Aggregates the proxy access meter over YOUR tokens only: per (app_id, op) call counts with an ok-count and a last timestamp, plus the 50 most recent events. A read logged under someone else's token is never counted. Optional ?app_id narrows both halves to one app.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"app_id","in":"query","required":false,"schema":{"type":"string"},"description":"Narrow the rollup and the recent list to one app."}],"responses":{"200":{"description":"Usage rollup","content":{"application/json":{"schema":{"type":"object","properties":{"totals":{"type":"object","properties":{"calls":{"type":"integer"},"ok_calls":{"type":"integer"}}},"by_op":{"type":"array","items":{"type":"object","properties":{"app_id":{"type":"string"},"op":{"type":"string"},"calls":{"type":"integer"},"ok_calls":{"type":"integer"},"last_at":{"type":"string","format":"date-time"}}}},"recent":{"type":"array","items":{"type":"object","properties":{"app_id":{"type":"string"},"op":{"type":"string"},"ok":{"type":"boolean"},"status":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developer/early-access":{"post":{"operationId":"submitDevEarlyAccess","summary":"Join the developer-platform early-access list","description":"Leaves an email address for the developer platform. DELIBERATELY ANONYMOUS (the point is a stranger leaving an address), rate-limited per IP. The answer is the SAME whether the address was new or already on the list, so no caller can test whether a given address signed up. 400 `invalid_email` on a malformed address.","tags":["Developer"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"source":{"type":"string","description":"Optional free-text origin label (normalized server-side)."}}}}}},"responses":{"201":{"description":"Recorded (same answer for a new and an existing address)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"invalid_email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listDevEarlyAccess","summary":"Read the early-access list (curator only)","description":"Returns the collected addresses. CURATOR ONLY through the same fail-closed comparison every other admin read uses: anonymous gets 401, an authenticated non-curator gets 403. Documented for completeness; an ordinary developer key can never read it.","tags":["Developer"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"The list","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"entries":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Login required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden: curator only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/autario.js":{"get":{"operationId":"getAutarioJs","summary":"autario.js, the data SDK for apps","description":"The one-file, zero-dependency data SDK every app on autario runs on (also served at https://autario.com/autario.js and /autario.v1.js). autario inlines it into every app it serves at /sandbox/{appId}/frame, so an app needs no script tag; this URL is for reading it and for loading it in a page outside autario. Calls: autario.ready(), autario.datasets(), autario.query(id, { columns, where, orderBy, limit, offset }), autario.csvUrl(id), autario.artifacts.get/set(key) (add { scope: 'viewer' } for one value per person looking at the app), autario.files.put/get/list/remove (images, PNG/JPEG/WebP/GIF, 2 MB, each viewer their own), autario.publicDatasets.search(q) and .query(id). Every call runs as the person looking at the app, through the sandbox bridge; no key or token ever reaches the app. Reference: https://autario.com/developer/docs/autario-js. No authentication; rate-limited with the documentation bucket.","tags":["Sandbox"],"responses":{"200":{"description":"The SDK source","content":{"application/javascript":{"schema":{"type":"string"}}}}}}},"/sandbox/{appId}/frame":{"get":{"operationId":"getSandboxFrame","summary":"The app's served bundle (iframe source, hard CSP)","description":"Serves the app's stored entry bundle as the iframe SOURCE document with the hard sandbox CSP (default-src 'none'; connect-src 'none' - no fetch/XHR/WebSocket can leave the frame). The host page frames this with sandbox=\"allow-scripts\" (null origin). ACCESS (since 2026-08-30): a PUBLIC app is served to anyone with no authentication, a PRIVATE app only to its owner (session cookie or account API key), and every other caller gets a plain-text 404 that never discloses whether the app exists. Apps registered through the Dev Portal are private by default, so this is the owner-only door for your own uploads and the anonymous door for the reference apps. Reading a reference app is still one request: GET /sandbox/ref-sparkline/frame returns the worked open-source example with autario.js inlined.","tags":["Sandbox"],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string","example":"ref-sparkline"}}],"responses":{"200":{"description":"The bundle document (text/html unless the bundle stored another content type)","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Unknown app or no bundle uploaded","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/sandbox/{appId}/read":{"post":{"operationId":"sandboxBridgeRead","summary":"The sandbox bridge read (anonymous-OK for public apps)","description":"The gated read bridge a sandboxed app's host relays postMessage requests to. Enforces the app's DECLARED manifest scope (consumed_datasets), then replays the app's server-side scoped token to the data proxy - the token never appears in the request or response. Anonymous-OK for a PUBLIC app (public data only), so a developer can test reads against the reference app's bridge WITHOUT an account: POST /sandbox/ref-sparkline/read with { op: 'markets', params: { ticker: 'MSFT' } }. A PRIVATE app (the default for anything you register) is owner-only: any other caller gets 404, the same answer an unknown app id gets. Body { op, params }; ops as in /proxy/read (markets, datasetMeta, datasetData). An op the manifest did not declare is refused.","tags":["Sandbox"],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string","example":"ref-sparkline"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["op"],"properties":{"op":{"type":"string","enum":["markets","datasetMeta","datasetData","sdk.context","sdk.datasets","sdk.query","sdk.search","sdk.artifact.get","sdk.rows.select"],"description":"The sdk.* ops are what autario.js sends. They run AS THE VIEWER (the session cookie of the page around the app) with that viewer's roles v1 role on this app: sdk.context -> { app, user: { id, role }, base_url } (user.id is an anonymous id, stable per app and viewer; the app owner in their own app gets their real id plus name and email); sdk.datasets -> the app owner's datasets the manifest declares (reader and up, [] for a visitor); sdk.query { id, columns, where, orderBy, limit, offset } -> { meta, data } (a public dataset for anyone, a private one only when it is the owner's AND declared AND the viewer is reader or up); sdk.search { q, limit } -> public catalogue hits; sdk.artifact.get { key } -> { key, value }; sdk.rows.select { dataset, columns, where, orderBy, limit, offset } -> { meta, data } of a dataset the app OWNS (manifest datasets_owned: scope app for reader and up, scope viewer = only the viewer's own rows, never the owner's view of them)."},"params":{"type":"object","description":"Op-specific params (e.g. { ticker } or { id, limit, filter, ... })"}}}}}},"responses":{"200":{"description":"Read result { ok, op, data }","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"op":{"type":"string"},"data":{"type":"object"}}}}}},"400":{"description":"Unknown op or bad params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"403":{"description":"Op not declared in the app's manifest scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"404":{"description":"Unknown app","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}}}}},"/sandbox/{appId}/write":{"post":{"operationId":"sandboxBridgeWrite","summary":"The sandbox bridge write","description":"The write mirror of /sandbox/{appId}/read. The host relays the iframe's autario.write here; the runtime enforces the app's DECLARED manifest scope, then delegates to the data proxy with the app's server-side token, which never appears in the request or the response. A SYSTEM app token is rejected for writes, so a write needs a user or workspace token behind the app. Same access gate as the other two sandbox doors: a public app is anonymous-OK, a private app is owner-only, and everything else answers 404. Body { op, params }; ops as in /proxy/write (artifactCreate, artifactUpdate).","tags":["Sandbox"],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["op"],"properties":{"op":{"type":"string","enum":["artifactCreate","artifactUpdate","sdk.artifact.set","sdk.rows.insert","sdk.rows.update","sdk.rows.delete"],"description":"sdk.artifact.set { key, value } is autario.artifacts.set: one JSON value of at most 256 KB per key, stored under the app owner, allowed for roles v1 editor and up on this app (403 role_required otherwise). sdk.rows.insert { dataset, rows } -> { ids }, sdk.rows.update { dataset, id, values }, sdk.rows.delete { dataset, ids } write a dataset the app OWNS (manifest datasets_owned): every row is checked against the declared columns (400 bad_rows), scope app needs editor and up, scope viewer writes only the viewer's own rows; any other dataset is 404."},"params":{"type":"object","description":"Op-specific params (e.g. { type, title, spec } or { id, ... })"}}}}}},"responses":{"200":{"description":"Write result { ok, op, data }","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"op":{"type":"string"},"data":{"type":"object"}}}}}},"400":{"description":"Unknown op or bad params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"403":{"description":"Op not declared in the app's manifest scope, or the app's token may not write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"404":{"description":"Unknown app, or an app this caller may not open","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}}}}},"/proxy/read":{"post":{"operationId":"proxyRead","summary":"Gated data read via a scoped app-token","description":"The single gated read choke-point for externalized / sandboxed apps. Auth is a SCOPED app-token (NOT an account API key) passed in the `x-api-key` + `x-api-secret` headers; the token's `scope` declares which ops (and optionally which dataset ids) it may read. Every read is authenticated, scope-checked, per-token rate-limited (~60 reads/min), audited, and then mapped onto the existing public read controllers (no new data path).\n\nBody `{ op, params }`. Supported ops:\n- `markets` - params `{ ticker }`; resolves a ticker to its datasets (ticker-keyed, not dataset-gated).\n- `datasetMeta` - params `{ id }`; public dataset metadata.\n- `datasetData` - params `{ id, ... }`; dataset rows (passes through limit/offset/fields/filter/sort/aggregate/groupby/shadow/summary_only/non_null_only). aggregates are numerically correct on numeric text-stored values (aggregate_meta.aggregates[].basis names the basis; min/max on a date column compare the text); summary_only returns finished stats with no rows; non_null_only drops empty rows.\n\nOn success returns `{ ok: true, op, data }` where `data` is the underlying controller body.","tags":["Proxy"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["op"],"properties":{"op":{"type":"string","enum":["markets","datasetMeta","datasetData"]},"params":{"type":"object","description":"Op-specific params (e.g. { ticker } or { id, limit, ... })"}}}}}},"responses":{"200":{"description":"Read result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"op":{"type":"string"},"data":{"type":"object","description":"The underlying public-controller response body"}}}}}},"400":{"description":"Unknown op or bad params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"401":{"description":"Missing or invalid scoped app-token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"403":{"description":"Op or dataset not allowed by token scope (or token is not a scoped app-token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"429":{"description":"Per-token rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error_code":{"type":"string","example":"rate_limited"},"error":{"type":"string"},"retry_after_ms":{"type":"integer"}}}}}}}}},"/proxy/write":{"post":{"operationId":"proxyWrite","summary":"Gated data write via a scoped app-token","description":"The write mirror of `/proxy/read`. Auth is a SCOPED app-token (`x-api-key` + `x-api-secret`). The token must be user/workspace-owned (a SYSTEM token is rejected) and its `scope` must grant the write op and name an `app_id`. Every write is authenticated, scope-checked, owner-checked, per-token write-rate-limited (stricter than reads), audited (the SAME access meter as reads), and applied through the artifact store's ownership lock.\n\nWrites touch ONLY the caller's own `app_artifacts` - never assets/datasets/core tables. Body `{ op, params }`. Supported ops:\n- `artifactCreate` - params `{ type, title?, spec?, data?, visibility? }`; creates an artifact in the token's app namespace, owned by the token owner.\n- `artifactUpdate` - params `{ id, title?, spec?, data?, visibility? }`; patches an artifact the caller OWNS (a cross-owner write is impossible).\n\nOn success returns `{ ok: true, id, app_id, type, slug, title, visibility, workspace_id, updated_at }`.","tags":["Proxy"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["op"],"properties":{"op":{"type":"string","enum":["artifactCreate","artifactUpdate"]},"params":{"type":"object","description":"Op-specific params (e.g. { type, title, spec } or { id, visibility })"}}}}}},"responses":{"200":{"description":"Write result (the created/updated artifact projection)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"id":{"type":"string","format":"uuid"},"app_id":{"type":"string"},"type":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"visibility":{"type":"string"},"workspace_id":{"type":"string","nullable":true},"updated_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Unknown write op or bad params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"401":{"description":"Missing or invalid scoped app-token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"403":{"description":"System token (cannot write), op not in scope, or not the owner of the target artifact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"429":{"description":"Per-token write rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error_code":{"type":"string","example":"rate_limited"},"error":{"type":"string"},"retry_after_ms":{"type":"integer"}}}}}}}}},"/proxy/token":{"post":{"operationId":"issueProxyToken","summary":"Mint a scoped app-token","description":"Mints a narrow, scoped app-token owned by the caller. Auth is NORMAL user-auth (login cookie or account API key); 401 without. Body `{ name, scope }` where `scope.ops` is a non-empty array of allowed ops (read ops `markets`/`datasetMeta`/`datasetData` and/or write ops `artifactCreate`/`artifactUpdate`), `scope.datasets` (optional) restricts dataset-keyed reads, and `scope.app_id` (REQUIRED when any write op is granted) names the app namespace writes land in. Returns the token `key` plus its `secret` - the secret is shown ONCE and is never retrievable again. The sandbox host holds this token server-side so app code never sees a broad key.","tags":["Proxy"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","scope"],"properties":{"name":{"type":"string","example":"bubble-or-not read token"},"scope":{"type":"object","required":["ops"],"properties":{"ops":{"type":"array","items":{"type":"string","enum":["markets","datasetMeta","datasetData","artifactCreate","artifactUpdate"]},"description":"Non-empty list of allowed ops (reads and/or writes)"},"datasets":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Optional allow-list restricting dataset-keyed reads"},"app_id":{"type":"string","description":"App id this token belongs to (audited); REQUIRED when the scope grants a write op or is workspace-scoped"},"workspace_id":{"type":"string","format":"uuid","description":"Optional workspace scope. Minted ONLY if the caller is a MEMBER of the workspace and the app is INSTALLED in it (else 403). Reads then see the workspace's private assets; writes tag the artifact to the workspace."}}}}}}}},"responses":{"200":{"description":"Minted token. `secret` is shown ONCE.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key":{"type":"string","description":"Public token key (x-api-key for /proxy/read)"},"created_at":{"type":"string","format":"date-time"},"scope":{"type":"object"},"secret":{"type":"string","description":"Token secret (x-api-secret) - shown ONCE, never retrievable again"}}}}}},"400":{"description":"Missing name or invalid scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"401":{"description":"Login or account API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}},"403":{"description":"Workspace-scoped token requested but the caller is not a member, or the app is not installed in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProxyError"}}}}}}},"/admin/connector-health":{"servers":[{"url":"https://autario.com/api","description":"Admin mount (/api, not /api/v1)"}],"get":{"operationId":"getConnectorHealth","summary":"One health row per gallery connector (curator only)","description":"ONE row per connector the gallery offers: logo, title, provider, auth kind, OAuth access state, pilot accounts, vendor review, users and instances connected, a derived status and the dominant open issue as one message. STATUS, first match wins: broken_by_us (our last runs failed on our own request) > vendor_issue (open issues, mostly the vendor's fault) > needs_user_action (open issues of cause permission or user_input) > in_review / testers_only (OAuth login not public) > suspended (new connections paused by the preset) > unverified (never delivered rows) > verified. Rows sorted by status, then users. CURATOR ONLY (session cookie or the curator API key pair): anyone else gets 403. The same rows as the MCP tool connector_health. Full URL: https://autario.com/api/admin/connector-health.","tags":["Admin"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Only the rows with this status.","schema":{"type":"string","enum":["broken_by_us","vendor_issue","needs_user_action","in_review","testers_only","unverified","verified"]}}],"responses":{"200":{"description":"The rows","content":{"application/json":{"schema":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time"},"rows":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"title":{"type":"string"},"logo_url":{"type":"string","nullable":true,"description":"Same-origin logo path (/connector-logos/<provider>.png)."},"auth_kind":{"type":"string","enum":["oauth","key","none"]},"access":{"type":"string","nullable":true,"enum":["public","testers_only","in_review","no_row"],"description":"The OAuth login state; null for a key connector or when unknown."},"pilot_accounts":{"type":"integer","nullable":true,"description":"Accounts allowed through a non-public login (OAuth only)."},"review":{"type":"string","nullable":true,"description":"Vendor review state (none, draft, submitted, approved, rejected, not_needed)."},"users":{"type":"integer"},"instances":{"type":"integer"},"status":{"type":"string","enum":["broken_by_us","vendor_issue","needs_user_action","in_review","testers_only","unverified","verified"]},"message":{"type":"string","nullable":true,"description":"The dominant open issue: cause, count, accounts and the vendor's sentence. null when clean."},"last_ok_at":{"type":"string","format":"date-time","nullable":true},"last_issue_at":{"type":"string","format":"date-time","nullable":true},"coverage":{"type":"object","properties":{"reports":{"type":"integer"},"audited":{"type":"boolean"},"findings_open":{"type":"array","items":{"type":"string"}}}}}}}}}}}},"403":{"description":"forbidden: curator only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sharing":{"servers":[{"url":"https://autario.com/api","description":"Account mount (/api, not /api/v1)"}],"get":{"operationId":"getSharingOverview","summary":"Everything this account shares, and what is shared with it","description":"One read of every live share this account owns (any app, any subject kind: dataset, brand, client, account) with its state, reach, views and the page that manages it, the account-level sharing switch, and the datasets and team memberships other accounts share WITH this one. Read-only: pause, resume and a new link go through /shares/{appId}/{subjectKind}/{subjectId}. SIGNED-IN BROWSER SESSION ONLY (cookie); an API key is refused. Never returns a share link (links are stored as a hash). Full URL: https://autario.com/api/sharing.","tags":["Sharing"],"responses":{"200":{"description":"The overview","content":{"application/json":{"schema":{"type":"object","properties":{"sharing_enabled":{"type":"boolean","description":"The account switch. false = every share of this account is refused at read time (nothing deleted)."},"shares":{"type":"array","items":{"type":"object","properties":{"app_id":{"type":"string"},"app":{"type":"string"},"subject_kind":{"type":"string","enum":["dataset","brand","client","account"]},"subject":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"href":{"type":"string","nullable":true,"description":"The page that manages this share."}}},"state":{"type":"string","enum":["active","paused","expired"]},"active":{"type":"boolean"},"paused_by_account":{"type":"boolean"},"scope":{"type":"string","enum":["link","domain","emails"]},"allowed_domains":{"type":"array","items":{"type":"string"}},"allowed_emails":{"type":"array","items":{"type":"string"}},"reach":{"type":"string","nullable":true},"view_count":{"type":"integer"},"last_viewed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"shared_with_you":{"type":"object","properties":{"brands":{"type":"array","description":"Brands another account shared with you in product: every current and future connector and table of the brand. covers = what it holds today, counted from the rows below (connectors and tables carrying this brand_id).","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"shared_by":{"type":"string"},"scope":{"type":"string","enum":["domain","emails"],"nullable":true},"covers":{"type":"object","properties":{"connectors":{"type":"integer"},"datasets":{"type":"integer"}}},"href":{"type":"string"}}}},"instances":{"type":"array","description":"Connector instances another account shared with you. brand_id names the shared brand the instance belongs to, null for a direct instance share.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"connector":{"type":"string","nullable":true},"provider":{"type":"string","nullable":true},"shared_by":{"type":"string"},"last_run_at":{"type":"string","format":"date-time","nullable":true},"brand_id":{"type":"string","nullable":true},"href":{"type":"string"}}}},"datasets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"shared_by":{"type":"string"},"rows":{"type":"integer","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true},"brand_id":{"type":"string","nullable":true,"description":"The shared brand this table belongs to, null for a direct dataset share."},"href":{"type":"string","nullable":true}}}},"teams":{"type":"array","items":{"type":"object","properties":{"owner":{"type":"string"},"roles":{"type":"object","additionalProperties":{"type":"string"}},"since":{"type":"string","format":"date-time","nullable":true}}}}}}}}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ai/charts":{"servers":[{"url":"https://autario.com/api","description":"Chart API mount (/api, not /api/v1)"}],"get":{"operationId":"listCharts","summary":"List published charts","description":"Lists public charts (plus your own with auth). NOTE: the chart API mounts under /api (this path item overrides the server URL), so the full URL is https://autario.com/api/ai/charts.","tags":["Charts"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search term matched against chart titles"},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Chart list","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"data":{"type":"array","items":{"type":"object"}}}}}}}}}},"/ai/chart/{id}":{"servers":[{"url":"https://autario.com/api","description":"Chart API mount (/api, not /api/v1)"}],"get":{"operationId":"getChart","summary":"Get a chart with its Plotly spec, data and embed code","description":"Returns one chart: title, Plotly spec (traces + layout), trimmed data, insight and embed code. A private chart returns a locked stub to a non-owner. Full URL: https://autario.com/api/ai/chart/{id}.","tags":["Charts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Chart id or slug"}],"responses":{"200":{"description":"The chart","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Chart not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ai/chart/publish":{"servers":[{"url":"https://autario.com/api","description":"Chart API mount (/api, not /api/v1)"}],"post":{"operationId":"publishChart","summary":"Publish a chart from a Plotly spec","description":"Publishes a chart from a Plotly spec plus dataset references. autario pulls the REAL rows from dataset_ids server-side (no raw data in the request, no hallucinated values) and runs the canonical publish pipeline. AUTH REQUIRED (x-api-key + x-api-secret). MCP equivalent: publish_chart. Full URL: https://autario.com/api/ai/chart/publish.","tags":["Charts"],"security":[{"ApiKeyAuth":[],"ApiSecretAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","plotly_spec","dataset_ids"],"properties":{"title":{"type":"string"},"plotly_spec":{"type":"object","description":"{ traces, layout } referencing dataset columns"},"dataset_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Datasets the chart plots (attribution + server-side data pull)"},"insight":{"type":"string","description":"Your written insight; verified against the data server-side"}}}}}},"responses":{"200":{"description":"Published chart","content":{"application/json":{"schema":{"type":"object","properties":{"chart_id":{"type":"string"},"url":{"type":"string"},"datasets_used":{"type":"array","items":{"type":"object"}},"rows_loaded":{"type":"integer"}}}}}},"400":{"description":"Invalid spec or datasets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials"}}}}},"tags":[{"name":"Public","description":"No authentication required. For discovery and schema inspection."},{"name":"Private","description":"Requires x-api-key + x-api-secret headers. For data access."},{"name":"Apps","description":"App submission-storage contract: register a manifest + upload a bundle. GET manifest is public; writes are key-gated."},{"name":"Developer","description":"Dev Portal: manage YOUR OWN apps, scoped tokens and access meter at /developer. Session cookie or account API key; every door is owner-scoped and a not-owned resource answers 404."},{"name":"Proxy","description":"Gated data-access proxy for externalized/sandboxed apps. Reads use a scoped app-token, minted via /proxy/token."},{"name":"Sandbox","description":"Tier-2 sandbox runtime: the served bundle (hard CSP) plus the read/write bridge, scope-bounded by the app's manifest. Public apps are anonymous-OK, private apps are owner-only, everything else is 404."},{"name":"Charts","description":"Chart list/read/publish. Mounts under /api (path-level servers override), not /api/v1."}]}