{"openapi":"3.1.0","info":{"title":"Argus API","version":"1","description":"Argus API v1: spend, balances and rate-limit headroom across the APIs you pay for.\nAuthenticate reads with an `api` key as `Authorization: Bearer <key>`. Every key sees one project.\nOperations marked `x-access: session` are for the signed-in web app; API keys get `session_required`.\nOperations marked `x-web: true` also accept the web app's session, which API clients never use.\nOperations with `x-mcp-key-types` are also MCP tools of the same name at `POST https://mcp.argus.town`, for keys of those types.\nSend events with a source secret (`Authorization: Bearer argus_src_...` plus `Argus-Source`) or HMAC headers. A source credential can write events and read nothing; an API key cannot write events.\nResponses are bare resources with an `object` tag; lists are `{object: \"list\", data, has_more, next_cursor}`.\nErrors are `{error: {type, code, message, param, doc_url, next_step, request_id}}` with real HTTP statuses.\nUnknown query parameters are rejected. Ids are prefixed (`conn_...`); bare ids are accepted on input.\nWithin v1 changes are additive: ignore fields you do not recognise."},"servers":[{"url":"https://api.argus.town"}],"paths":{"/v1":{"get":{"operationId":"index_get","tags":["Start"],"summary":"API index","description":"Self-describing entry point: where the contract, error catalog and MCP endpoint live, how to authenticate, and the first authenticated call.","security":[],"x-access":"public","parameters":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndex"},"examples":{"index":{"summary":"index","value":{"object":"api","version":"v1","status":"ok","links":{"documentation":"https://argus.town/docs/api","openapi":"/v1/openapi.json","errors":"/v1/errors","providers":"/v1/providers","mcp":"https://mcp.argus.town"},"authentication":{"scheme":"bearer","key_type":"api","create_key_url":"https://argus.town/settings"},"first_call":{"method":"GET","href":"/v1/project","curl":"curl -s https://api.argus.town/v1/project -H \"Authorization: Bearer $ARGUS_API_KEY\""},"next_steps":[{"rel":"list_providers","method":"GET","href":"/v1/providers","why":"See which providers Argus covers, no key needed."}]}}}}}}},"x-argus-examples":[{"name":"index","request":{"method":"GET","path":"/v1"},"status":200}]}},"/v1/providers":{"get":{"operationId":"providers_list","tags":["Providers"],"summary":"List providers","description":"The provider catalog: pricing model and whether Argus can poll the provider with a credential. Public, no key.","security":[],"x-access":"public","x-mcp-key-types":["api","mcp"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size. Default 25.","schema":{"$ref":"#/components/schemas/Int","description":"a number between 1 and 200","title":"between(1, 200)","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous page's `next_cursor`.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"connectable","in":"query","required":false,"description":"Only providers Argus can poll (true) or only telemetry-only ones (false).","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderList"},"examples":{"connectable":{"summary":"connectable","value":{"object":"list","data":[{"object":"provider","id":"openrouter","pricing_model":"usage_drawdown","summary":"Prepaid credits drawn down per request across many model providers.","connectable":true,"credential_types":["api_key"]}],"has_more":true,"next_cursor":"WyJvcGVucm91dGVyIl0"}}}}}},"400":{"description":"Error. Codes: invalid_parameter, invalid_cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"connectable","request":{"method":"GET","path":"/v1/providers?connectable=true&limit=1"},"status":200}]}},"/v1/providers/{slug}":{"get":{"operationId":"providers_get","tags":["Providers"],"summary":"Get a provider","description":"One provider with its full offering: plans, rate limits and how spend is observed.","security":[],"x-access":"public","x-mcp-key-types":["api","mcp"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Provider slug, for example `openrouter`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Provider"},"examples":{"openrouter":{"summary":"openrouter","value":{"object":"provider","id":"openrouter","pricing_model":"usage_drawdown","summary":"Prepaid credits drawn down per request across many model providers.","connectable":true,"credential_types":["api_key"],"offering":{"provider":"openrouter"}}}}}}},"404":{"description":"Error. Codes: provider_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unknown":{"summary":"unknown","value":{"error":{"type":"not_found","code":"provider_not_found","message":"No provider has the slug nope.","param":null,"doc_url":"https://argus.town/docs/errors#provider_not_found","next_step":{"hint":"List provider slugs.","method":"GET","href":"/v1/providers"},"request_id":null}}}}}}}},"x-argus-examples":[{"name":"openrouter","request":{"method":"GET","path":"/v1/providers/openrouter"},"status":200},{"name":"unknown","request":{"method":"GET","path":"/v1/providers/nope"},"status":404}]}},"/v1/device/code":{"post":{"operationId":"device_code","tags":["Start"],"summary":"Start device login","description":"For an agent with no credentials: ask for access, show the human `verification_uri_complete`, and poll `POST /v1/device/token`. The human signs in, picks the project and approves the scopes listed; nothing is issued before that. `api` (alias `read`) is an API key, which can read spend and also create and update connections, alert rules and negotiated pricing in the approved project; `ingest` is a telemetry source; `mcp` is an MCP key. Without `scopes`: `api` and `ingest`. Rate limited per address.","security":[],"x-access":"public","parameters":[],"requestBody":{"required":true,"description":"Optional client name and scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceCodeBody"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceCode"},"examples":{"api and ingest":{"summary":"api and ingest","value":{"object":"device_code","device_code":"argus_dev_3b9f0c5e1a7d4826b0c9e3f5a1d7b2c84e6f0a9d3c5b7e1f","user_code":"BCDF-GHJK","verification_uri":"https://argus.town/device","verification_uri_complete":"https://argus.town/device?code=BCDF-GHJK","expires_in":900,"interval":7}}}}}},"400":{"description":"Error. Codes: invalid_request_body, invalid_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unknown scope":{"summary":"unknown scope","value":{"error":{"type":"invalid_request","code":"invalid_parameter","message":"Invalid value for \"scopes[0]\": Expected \"api\" | \"read\" | \"ingest\" | \"mcp\", actual \"admin\"","param":"scopes[0]","doc_url":"https://argus.town/docs/errors#invalid_parameter","request_id":null}}}}}}},"413":{"description":"Error. Codes: payload_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"api and ingest","request":{"method":"POST","path":"/v1/device/code","body":{"client_name":"my-agent","scopes":["api","ingest"]}},"status":201},{"name":"unknown scope","request":{"method":"POST","path":"/v1/device/code","body":{"scopes":["admin"]}},"status":400}]}},"/v1/device/token":{"post":{"operationId":"device_token","tags":["Start"],"summary":"Poll device login","description":"Poll with the `device_code` until `status` leaves `pending`. On `approved` the credentials are returned once (`api_key`, `source.secret`, `mcp_key` as requested) together with the project; later polls say `consumed`. `denied`, `expired`, `consumed` and `invalid` are final: start again. Rate limited per code and, for unknown codes, per address.","security":[],"x-access":"public","parameters":[],"requestBody":{"required":true,"description":"The device code from the first step.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceTokenBody"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceToken"},"examples":{"pending":{"summary":"pending","value":{"object":"device_token","status":"pending","next_steps":[{"rel":"poll","method":"POST","href":"/v1/device/token","why":"Not approved yet. Poll again in 7 seconds."}]}},"unknown code":{"summary":"unknown code","value":{"object":"device_token","status":"invalid","next_steps":[{"rel":"restart","method":"POST","href":"/v1/device/code","why":"This code cannot yield credentials. Start again."}]}}}}}},"400":{"description":"Error. Codes: invalid_request_body, invalid_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"413":{"description":"Error. Codes: payload_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"pending","request":{"method":"POST","path":"/v1/device/token","body":{"device_code":"{device_code.device_code}"}},"status":200},{"name":"unknown code","request":{"method":"POST","path":"/v1/device/token","body":{"device_code":"argus_dev_nope"}},"status":200}]}},"/v1/project":{"get":{"operationId":"project_get","tags":["Project"],"summary":"Get the key's project","description":"Who am I: the project this key belongs to, the key itself, what it may call, the plan, and what to do next.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-mcp-key-types":["api"],"parameters":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"},"examples":{"empty project":{"summary":"empty project","value":{"object":"project","id":"prj_org_3kQ9vXw2","name":"Acme","created_at":"2026-10-01T09:30:00.000Z","key":{"object":"key","id":"key_7d2e91a0","type":"api","name":"ci","prefix":"argus_api_ab12"},"permissions":["project_get","summary_get","connections_list","connections_get"],"plan":{"id":"free","name":"Free"},"next_steps":[{"rel":"list_providers","method":"GET","href":"/v1/providers?connectable=true","why":"No connections yet. See which providers Argus can poll."}]}}}}}},"400":{"description":"Error. Codes: unknown_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"empty project","request":{"method":"GET","path":"/v1/project"},"status":200}]}},"/v1/summary":{"get":{"operationId":"summary_get","tags":["Spend"],"summary":"Spend summary","description":"What the project is spending and what is about to run out: month-to-date and projected totals, every connection with its metrics, and advisories.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api","mcp"],"parameters":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Summary"},"examples":{"one connection":{"summary":"one connection","value":{"object":"summary","totals":{"mtd_spend_usd":18.4,"projected_month_end_usd":55.2},"connections":[{"object":"connection","id":"conn_0b6f2c1e-6c1d-4a39-9f43-5b0d2f7a8c11","provider":"openrouter","origin":"poll","label":"OpenRouter (production)","credential_type":"api_key","status":"active","status_detail":null,"last_synced_at":"2026-10-01T09:30:00.000Z","created_at":"2026-10-01T09:30:00.000Z","updated_at":"2026-10-01T09:30:00.000Z","metrics":{"balance_usd":42.5,"burn_per_day":3.1,"days_to_zero":13.7,"mtd_spend_usd":18.4,"spend_basis":"reported","observed_since":null,"balance_scope":"account","projected_month_end_usd":55.2,"wow_change_pct":4.2,"rate_limit_headroom_pct":80,"error_rate_pct":0.4,"accuracy":"exact","cost_drift_pct":0.3,"billing_mode":"usage_drawdown","utilization_pct":null,"used_amount":null,"included_amount":null,"included_meter_id":null,"subscription_fee_usd":null,"effective_usd_per_unit":null,"days_to_reset":null,"recommended_action":null,"recommended_tier":null,"recommended_delta_usd":null},"metered":true}],"advisories":[],"next_steps":[]}}}}}},"400":{"description":"Error. Codes: unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"one connection","request":{"method":"GET","path":"/v1/summary"},"status":200}]}},"/v1/connections":{"get":{"operationId":"connections_list","tags":["Connections"],"summary":"List connections","description":"Providers the project tracks, polled, pushed or both, newest first. Credentials are never returned.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api","mcp"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size. Default 25.","schema":{"$ref":"#/components/schemas/Int","description":"a number between 1 and 200","title":"between(1, 200)","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous page's `next_cursor`.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"provider","in":"query","required":false,"description":"Only connections to this provider slug.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"status","in":"query","required":false,"description":"Only connections in this status.","schema":{"type":"string","enum":["active","invalid","expired","suspended"]}},{"name":"origin","in":"query","required":false,"description":"Only connections fed this way.","schema":{"type":"string","enum":["poll","push","both"]}},{"name":"expand[]","in":"query","required":false,"description":"Fields to include. One or more of: metrics, advisories.","schema":{"type":"array","items":{"type":"string","enum":["metrics","advisories"]}},"style":"form","explode":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionList"},"examples":{"with metrics":{"summary":"with metrics","value":{"object":"list","data":[{"object":"connection","id":"conn_0b6f2c1e-6c1d-4a39-9f43-5b0d2f7a8c11","provider":"openrouter","origin":"poll","label":"OpenRouter (production)","credential_type":"api_key","status":"active","status_detail":null,"last_synced_at":"2026-10-01T09:30:00.000Z","created_at":"2026-10-01T09:30:00.000Z","updated_at":"2026-10-01T09:30:00.000Z","metrics":{"balance_usd":42.5,"burn_per_day":3.1,"days_to_zero":13.7,"mtd_spend_usd":18.4,"spend_basis":"reported","observed_since":null,"balance_scope":"account","projected_month_end_usd":55.2,"wow_change_pct":4.2,"rate_limit_headroom_pct":80,"error_rate_pct":0.4,"accuracy":"exact","cost_drift_pct":0.3,"billing_mode":"usage_drawdown","utilization_pct":null,"used_amount":null,"included_amount":null,"included_meter_id":null,"subscription_fee_usd":null,"effective_usd_per_unit":null,"days_to_reset":null,"recommended_action":null,"recommended_tier":null,"recommended_delta_usd":null},"metered":true}],"has_more":false,"next_cursor":null}}}}}},"400":{"description":"Error. Codes: invalid_parameter, invalid_cursor, unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"with metrics","request":{"method":"GET","path":"/v1/connections?limit=10&expand[]=metrics"},"status":200}]},"post":{"operationId":"connections_create","tags":["Connections"],"summary":"Connect a provider","description":"Poll a provider with a credential. Argus checks the credential with the provider before storing it (encrypted; it is never returned) and queues the first sync. A repeated `label` for the same provider is a 409 `label_conflict`: rotate the credential with `PATCH /v1/connections/{id}` instead. Without a `label` an extra account gets a distinct default one. A provider the project already tracks by telemetry only (no label given) is upgraded in place (`origin: both`). At most 100 polled connections per project (telemetry-only ones are capped separately).","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api","mcp"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 255 printable ASCII characters. A retry with the same key and body replays the first response (`Idempotent-Replayed: true`) for 24 hours; the same key with a different body is a 409, and so is a duplicate that arrives while the first request is still running.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The provider, its credential and optionally a label.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionCreateBody"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"},"examples":{"connect":{"summary":"connect","value":{"object":"connection","id":"conn_0b6f2c1e-6c1d-4a39-9f43-5b0d2f7a8c11","provider":"millionverifier","origin":"poll","label":"Verifier","credential_type":"api_key","status":"active","status_detail":null,"last_synced_at":null,"created_at":"2026-10-01T09:30:00.000Z","updated_at":"2026-10-01T09:30:00.000Z"}}}}}},"400":{"description":"Error. Codes: invalid_request_body, invalid_parameter, missing_parameter, invalid_idempotency_key, unknown_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"409":{"description":"Error. Codes: idempotency_key_reused, label_conflict, quota_exceeded, idempotency_key_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"repeated label":{"summary":"repeated label","value":{"error":{"type":"conflict","code":"label_conflict","message":"Another millionverifier connection is named \"Verifier\".","param":"label","doc_url":"https://argus.town/docs/errors#label_conflict","request_id":null}}}}}}},"413":{"description":"Error. Codes: payload_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"422":{"description":"Error. Codes: provider_not_connectable, credential_invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"502":{"description":"Error. Codes: provider_unreachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"connect","request":{"method":"POST","path":"/v1/connections","body":{"provider":"millionverifier","secret":"mv-example-key","label":"Verifier"}},"status":201},{"name":"repeated label","request":{"method":"POST","path":"/v1/connections","body":{"provider":"millionverifier","secret":"mv-example-key","label":"Verifier"}},"status":409}]}},"/v1/connections/{id}":{"get":{"operationId":"connections_get","tags":["Connections"],"summary":"Get a connection","description":"One connection. Expand `usage`, `breakdown`, `rate_limits`, `sync_runs` and `plan` for the detail view; expansions only add fields.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api","mcp"],"parameters":[{"name":"id","in":"path","required":true,"description":"Connection id, with or without the `conn_` prefix.","schema":{"type":"string"}},{"name":"expand[]","in":"query","required":false,"description":"Fields to include. One or more of: metrics, advisories, usage, breakdown, rate_limits, sync_runs, plan.","schema":{"type":"array","items":{"type":"string","enum":["metrics","advisories","usage","breakdown","rate_limits","sync_runs","plan"]}},"style":"form","explode":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"},"examples":{"with plan":{"summary":"with plan","value":{"object":"connection","id":"conn_0b6f2c1e-6c1d-4a39-9f43-5b0d2f7a8c11","provider":"openrouter","origin":"poll","label":"OpenRouter (production)","credential_type":"api_key","status":"active","status_detail":null,"last_synced_at":"2026-10-01T09:30:00.000Z","created_at":"2026-10-01T09:30:00.000Z","updated_at":"2026-10-01T09:30:00.000Z","plan":null}}}}}},"400":{"description":"Error. Codes: invalid_parameter, unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"404":{"description":"Error. Codes: connection_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"with plan","request":{"method":"GET","path":"/v1/connections/{id}?expand[]=plan"},"status":200}]},"patch":{"operationId":"connections_update","tags":["Connections"],"summary":"Update a connection","description":"Relabel a connection or rotate its credential. Send `secret` to rotate: it is checked with the provider, replaces the stored credential and re-queues a sync. `credential_type` and `meta` are part of the credential, so they are accepted only together with `secret` (non-secret fields you leave out of `meta` keep their stored values). A connection an operator suspended stays suspended. Credentials of AI-built connectors rotate in the app. Nothing secret is ever returned.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api"],"parameters":[{"name":"id","in":"path","required":true,"description":"Connection id, with or without the `conn_` prefix.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 255 printable ASCII characters. A retry with the same key and body replays the first response (`Idempotent-Replayed: true`) for 24 hours; the same key with a different body is a 409, and so is a duplicate that arrives while the first request is still running.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"At least one of `label` or `secret`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionUpdateBody"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"},"examples":{"relabel":{"summary":"relabel","value":{"object":"connection","id":"conn_0b6f2c1e-6c1d-4a39-9f43-5b0d2f7a8c11","provider":"openai","origin":"poll","label":"OpenAI (production)","credential_type":"api_key","status":"active","status_detail":null,"last_synced_at":"2026-10-01T09:30:00.000Z","created_at":"2026-10-01T09:30:00.000Z","updated_at":"2026-10-01T09:30:00.000Z"}}}}}},"400":{"description":"Error. Codes: invalid_request_body, invalid_parameter, invalid_idempotency_key, unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"meta without secret":{"summary":"meta without secret","value":{"error":{"type":"invalid_request","code":"invalid_parameter","message":"\"meta\" can only change together with \"secret\": it is validated and stored with the credential.","param":"meta","doc_url":"https://argus.town/docs/errors#invalid_parameter","request_id":null}}}}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"404":{"description":"Error. Codes: connection_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"409":{"description":"Error. Codes: idempotency_key_reused, label_conflict, idempotency_key_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"413":{"description":"Error. Codes: payload_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"422":{"description":"Error. Codes: credential_invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"502":{"description":"Error. Codes: provider_unreachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"relabel","request":{"method":"PATCH","path":"/v1/connections/{id}","body":{"label":"OpenAI (production)"}},"status":200},{"name":"meta without secret","request":{"method":"PATCH","path":"/v1/connections/{id}","body":{"meta":{"account_id":"acct_1"}}},"status":400}]},"delete":{"operationId":"connections_delete","tags":["Connections"],"summary":"Delete a connection","description":"Stop tracking a provider and delete its stored credential and history. Session only: an API key is refused with `session_required`. Unknown ids are a 404.","security":[{"sessionCookie":[]}],"x-access":"session","parameters":[{"name":"id","in":"path","required":true,"description":"Connection id, with or without the `conn_` prefix.","schema":{"type":"string"}}],"responses":{"204":{"description":"Success. No content."},"400":{"description":"Error. Codes: unknown_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: session_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"api key refused":{"summary":"api key refused","value":{"error":{"type":"permission_error","code":"session_required","message":"This action needs a signed-in session in the Argus app. API keys cannot perform it.","param":null,"doc_url":"https://argus.town/docs/errors#session_required","next_step":{"hint":"Do this from the Argus app, signed in as a member of the project.","href":"https://argus.town/settings"},"request_id":null}}}}}}},"404":{"description":"Error. Codes: connection_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"api key refused","request":{"method":"DELETE","path":"/v1/connections/{id}"},"status":403,"credential":"api_key"},{"name":"delete","request":{"method":"DELETE","path":"/v1/connections/{spare}"},"status":204}]}},"/v1/events":{"post":{"operationId":"events_create","tags":["Events"],"summary":"Send events","description":"Send one event or a batch of up to 1,000. Authenticate with a source secret (`Authorization: Bearer argus_src_...` plus `Argus-Source: <source id>`) or HMAC-sign the body as `POST /ingest` does. A source credential can only write events; it cannot read anything. Argus prices events without a `cost_usd` from `model` and `units`. Bad events are rejected one by one in `rejected`; the rest are queued. Re-sending an event `id` is a no-op, and an `Idempotency-Key` makes the whole request safe to retry for 24 hours. Bearer mode has no replay protection: a captured request can be replayed, so retry with the same `Idempotency-Key` (or give events ids). HMAC mode rejects timestamps more than 5 minutes off, and a replayed signed body without event ids derives the same ids and stores once. After a timeout, resend the identical signed request within 5 minutes or use explicit event ids: a re-signed retry derives new ids and can double-count if the first attempt died before its response was stored. Rate limits per source: 6,000 events and 600 requests a minute. Telemetry may create at most 10 new connections per request and 100 per project. `accepted` counts events queued: the queue consumer prices events without a `cost_usd` afterwards, and drops (and logs) an event whose derived cost exceeds 1,000,000 USD, which cannot be known at request time.","security":[{"sourceSecret":[]},{"sourceSignature":[]}],"x-access":"source","parameters":[{"name":"backfill","in":"query","required":false,"description":"Allow `occurred_at` up to 29 days back instead of 48 hours.","schema":{"type":"boolean"}},{"name":"Argus-Source","in":"header","required":false,"description":"Source id. Required with a bearer source secret.","schema":{"type":"string"}},{"name":"X-Argus-Source","in":"header","required":false,"description":"Source id, for HMAC signing.","schema":{"type":"string"}},{"name":"X-Argus-Timestamp","in":"header","required":false,"description":"Epoch milliseconds the body was signed at, for HMAC signing.","schema":{"type":"string"}},{"name":"X-Argus-Signature","in":"header","required":false,"description":"Hex HMAC-SHA256 signature, for HMAC signing.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 255 printable ASCII characters. A retry with the same key and body replays the first response (`Idempotent-Replayed: true`) for 24 hours; the same key with a different body is a 409, and so is a duplicate that arrives while the first request is still running.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"An event, or `{events: [...], backfill?: true}`. `backfill=true` as a query parameter works too.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EventsBody"},{"$ref":"#/components/schemas/EventInput"}]}}}},"responses":{"202":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventBatch"},"examples":{"one event":{"summary":"one event","value":{"object":"event_batch","accepted":1,"rejected":[],"rejected_count":0,"warnings":[],"warnings_count":0,"events":[{"id":"evt_6f1d2c4a9b8e47d3a05c1e7b9d2f4a68"}],"connections":[{"id":"conn_0b6f2c1e-6c1d-4a39-9f43-5b0d2f7a8c11","provider":"openai","created":false}],"next_steps":[{"rel":"read_events","method":"GET","href":"/v1/events?id=evt_6f1d2c4a9b8e47d3a05c1e7b9d2f4a68&since=2026-10-01T09%3A29%3A00.000Z&until=2026-10-01T09%3A31%3A00.000Z","why":"Read the event back once the queue has stored it, usually within seconds."}]}}}}}},"400":{"description":"Error. Codes: invalid_request_body, invalid_idempotency_key, invalid_parameter, unknown_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_source_credentials, invalid_source_credentials, timestamp_stale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"409":{"description":"Error. Codes: idempotency_key_reused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"413":{"description":"Error. Codes: payload_too_large, too_many_events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"422":{"description":"Error. Codes: no_valid_events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"every event rejected":{"summary":"every event rejected","value":{"error":{"type":"invalid_request","code":"no_valid_events","message":"None of the 1 events were valid. First: events[0]: event must be an object.","param":"events[0]","doc_url":"https://argus.town/docs/errors#no_valid_events","next_step":{"hint":"Validate the batch to see every rejection.","method":"POST","href":"/v1/events/validate"},"request_id":null}}}}}}},"429":{"description":"Error. Codes: too_many_auth_failures, rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"one event","request":{"method":"POST","path":"/v1/events","body":{"provider":"openai","model":"gpt-4o","units":{"input_tokens":900,"output_tokens":120},"metadata":{"run":"nightly"}}},"status":202},{"name":"every event rejected","request":{"method":"POST","path":"/v1/events","body":{"events":["not an event"]}},"status":422}]},"get":{"operationId":"events_list","tags":["Events"],"summary":"List events","description":"The project's call ledger, newest first, paged with a keyset cursor so events sharing a timestamp are never skipped. Time-bounded: `since` defaults to 31 days before `until` (default: 48 hours ahead of now) and the window is at most 31 days. `id` and `metadata[key]=value` filters need an explicit `since` and a window of at most 7 days. By default only events with a cost or a status of 400 or above are listed; `view=all` also lists cost-less events, and filtering by `id` or `cost_provenance` always does. Every accepted event counts toward `events_this_month` on `GET /billing`, listed or not.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, at most 500.","schema":{"$ref":"#/components/schemas/Int","description":"a number between 1 and 500","title":"between(1, 500)","minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous page's `next_cursor`.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"connection","in":"query","required":false,"description":"Only events of this connection (`conn_...`).","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"provider","in":"query","required":false,"description":"Only events of this provider slug.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"model","in":"query","required":false,"description":"Only events of this model.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"id","in":"query","required":false,"description":"Only the event with this id (any source of the project). Needs `since`, window of at most 7 days.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"status","in":"query","required":false,"description":"Only events with this HTTP status.","schema":{"$ref":"#/components/schemas/Int","description":"a number between 0 and 999","title":"between(0, 999)","minimum":0,"maximum":999}},{"name":"cost_provenance","in":"query","required":false,"description":"Only events whose cost was obtained this way.","schema":{"type":"string","enum":["provider_reported","app_reported","derived","unpriced"]}},{"name":"since","in":"query","required":false,"description":"Oldest `occurred_at`, inclusive.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"until","in":"query","required":false,"description":"Newest `occurred_at`, exclusive.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"view","in":"query","required":false,"description":"`all` lists cost-less events with a status below 400 too.","schema":{"type":"string","enum":["all"]}},{"name":"metadata","in":"query","required":false,"description":"Filter on metadata, for example `metadata[run]=nightly`. Up to 5; needs `since` (window of at most 7 days).","schema":{"type":"object","required":[],"properties":{},"additionalProperties":{"type":"string"}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventList"},"examples":{"recent":{"summary":"recent","value":{"object":"list","data":[{"object":"event","id":"01JAX7Q2M5N8R4T6V9W3Y1Z0BC","source":"src_5b1c0e9a","connection":"conn_0b6f2c1e-6c1d-4a39-9f43-5b0d2f7a8c11","provider":"openai","hostname":"api.openai.com","endpoint":"/v1/chat/completions","method":"POST","model":"gpt-4o","status":200,"latency_ms":812,"units":{"input_tokens":900,"output_tokens":120},"metadata":{"run":"nightly"},"cost_usd":0.00345,"cost_micros":3450,"cost_provenance":"derived","price_match":"exact","provider_request_id":null,"credits_spent":null,"credits_remaining":null,"occurred_at":"2026-10-01T09:30:00.000Z","received_at":"2026-10-01T09:30:00.000Z"}],"has_more":false,"next_cursor":null}}}}}},"400":{"description":"Error. Codes: invalid_parameter, invalid_cursor, unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: too_many_auth_failures, rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"recent","request":{"method":"GET","path":"/v1/events?limit=1&view=all"},"status":200}]}},"/v1/events/validate":{"post":{"operationId":"events_validate","tags":["Events"],"summary":"Validate events","description":"Runs the exact pipeline of `POST /v1/events` and stores nothing: which events would be accepted, which rejected and why, and the normalized events. Same credentials and body limits; counts against the same events rate limit.","security":[{"sourceSecret":[]},{"sourceSignature":[]}],"x-access":"source","parameters":[{"name":"backfill","in":"query","required":false,"description":"Validate as a backfill batch (`occurred_at` up to 29 days back).","schema":{"type":"boolean"}},{"name":"Argus-Source","in":"header","required":false,"description":"Source id. Required with a bearer source secret.","schema":{"type":"string"}},{"name":"X-Argus-Source","in":"header","required":false,"description":"Source id, for HMAC signing.","schema":{"type":"string"}},{"name":"X-Argus-Timestamp","in":"header","required":false,"description":"Epoch milliseconds the body was signed at, for HMAC signing.","schema":{"type":"string"}},{"name":"X-Argus-Signature","in":"header","required":false,"description":"Hex HMAC-SHA256 signature, for HMAC signing.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The same body as `POST /v1/events`.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EventsBody"},{"$ref":"#/components/schemas/EventInput"}]}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventValidation"},"examples":{"one bad, one good":{"summary":"one bad, one good","value":{"object":"event_validation","valid":false,"accepted":1,"rejected":[{"index":1,"id":null,"code":"invalid_event","message":"status must be a finite number"}],"rejected_count":1,"warnings":[{"index":0,"code":"unknown_field","field":"colour","message":"`colour` is not an event field and was ignored."}],"warnings_count":1,"normalized_events":[{"provider":"openai","model":"gpt-4o"}],"next_steps":[]}}}}}},"400":{"description":"Error. Codes: invalid_request_body, invalid_parameter, unknown_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_source_credentials, invalid_source_credentials, timestamp_stale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"413":{"description":"Error. Codes: payload_too_large, too_many_events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: too_many_auth_failures, rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"one bad, one good","request":{"method":"POST","path":"/v1/events/validate","body":{"events":[{"provider":"openai","model":"gpt-4o","colour":"red"},{"provider":"openai","status":"ok"}]}},"status":200}]}},"/v1/spend":{"get":{"operationId":"spend_get","tags":["Spend"],"summary":"Spend over time","description":"Daily spend for the project: totals and a day-by-day series, optionally split by `provider`, `connection` or `model`. Totals are the sum of the daily rollups. `model` groups use provider-reported breakdowns where a connection has them and itemized events otherwise, so they can sum to less than the day's spend. Defaults to the last 30 days; at most 366.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api","mcp"],"parameters":[{"name":"since","in":"query","required":false,"description":"First day, inclusive (rounded down to 00:00 UTC).","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"until","in":"query","required":false,"description":"Last day, exclusive (rounded up to 00:00 UTC). Default: tomorrow.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"granularity","in":"query","required":false,"description":"Bucket size. Only `day` for now.","schema":{"type":"string","enum":["day"]}},{"name":"group_by","in":"query","required":false,"description":"Split each day by this dimension.","schema":{"type":"string","enum":["provider","connection","model"]}},{"name":"provider","in":"query","required":false,"description":"Only this provider slug.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"connection","in":"query","required":false,"description":"Only this connection (`conn_...`).","schema":{"$ref":"#/components/schemas/NonEmptyString"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Spend"},"examples":{"by provider":{"summary":"by provider","value":{"object":"spend","since":"2026-09-21T00:00:00.000Z","until":"2026-10-22T00:00:00.000Z","granularity":"day","group_by":"provider","totals":{"spend_usd":18.4,"requests":1200,"tokens_input":900000,"tokens_output":120000,"errors":3},"series":[{"period_start":"2026-10-01T00:00:00.000Z","spend_usd":18.4,"requests":1200,"groups":[{"key":"openai","spend_usd":18.4,"requests":1200}]}],"next_steps":[]}}}}}},"400":{"description":"Error. Codes: invalid_parameter, unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: too_many_auth_failures, rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"by provider","request":{"method":"GET","path":"/v1/spend?group_by=provider"},"status":200}]}},"/v1/connections/{id}/syncs":{"post":{"operationId":"syncs_create","tags":["Syncs"],"summary":"Refresh a connection","description":"Queue an immediate refresh of balance, usage and plan, and get a sync to poll with `GET /v1/syncs/{id}`. At most one refresh is queued per connection a minute, whatever state the last one is in: a request inside that window returns the latest sync instead of queueing another. Telemetry-only and suspended connections have nothing to poll: 409 `connection_not_pollable`.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api","mcp"],"parameters":[{"name":"id","in":"path","required":true,"description":"Connection id, with or without the `conn_` prefix.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 255 printable ASCII characters. A retry with the same key and body replays the first response (`Idempotent-Replayed: true`) for 24 hours; the same key with a different body is a 409, and so is a duplicate that arrives while the first request is still running.","schema":{"type":"string"}}],"responses":{"202":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sync"},"examples":{"queued":{"summary":"queued","value":{"object":"sync","id":"sync_5d0c7a21-8e4b-4f6a-9c13-2b7e1a90d4f8","kind":"refresh","status":"queued","started_at":"2026-10-01T09:30:00.000Z","finished_at":null,"records_written":0,"error":null}}}}}},"400":{"description":"Error. Codes: invalid_idempotency_key, unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"404":{"description":"Error. Codes: connection_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"409":{"description":"Error. Codes: connection_not_pollable, idempotency_key_reused, idempotency_key_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"telemetry only":{"summary":"telemetry only","value":{"error":{"type":"conflict","code":"connection_not_pollable","message":"This connection only receives telemetry, so there is nothing to refresh.","param":null,"doc_url":"https://argus.town/docs/errors#connection_not_pollable","request_id":null}}}}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"queued","request":{"method":"POST","path":"/v1/connections/{connection}/syncs"},"status":202},{"name":"telemetry only","request":{"method":"POST","path":"/v1/connections/{id}/syncs"},"status":409}]},"get":{"operationId":"syncs_list","tags":["Syncs"],"summary":"List refreshes","description":"Refreshes requested for the connection, newest first. A sync is `queued`, `running` once some of its runs have reported, then `success`, `partial` or `error`. A transient provider error reads `partial` until the retry lands; a sync the queue never finished is closed after 30 minutes with what it has.","security":[{"bearerAuth":[]}],"x-access":"api_key","parameters":[{"name":"id","in":"path","required":true,"description":"Connection id, with or without the `conn_` prefix.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 25.","schema":{"$ref":"#/components/schemas/Int","description":"a number between 1 and 200","title":"between(1, 200)","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous page's `next_cursor`.","schema":{"$ref":"#/components/schemas/NonEmptyString"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncList"},"examples":{"history":{"summary":"history","value":{"object":"list","data":[{"object":"sync","id":"sync_5d0c7a21-8e4b-4f6a-9c13-2b7e1a90d4f8","kind":"refresh","status":"queued","started_at":"2026-10-01T09:30:00.000Z","finished_at":null,"records_written":0,"error":null}],"has_more":false,"next_cursor":null}}}}}},"400":{"description":"Error. Codes: invalid_parameter, invalid_cursor, unknown_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"404":{"description":"Error. Codes: connection_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"history","request":{"method":"GET","path":"/v1/connections/{connection}/syncs?limit=5"},"status":200}]}},"/v1/syncs/{id}":{"get":{"operationId":"syncs_get","tags":["Syncs"],"summary":"Get a sync","description":"One refresh, or one scheduled run as listed under a connection's `sync_runs` expansion.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api"],"parameters":[{"name":"id","in":"path","required":true,"description":"Sync id, with or without the `sync_` prefix.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sync"},"examples":{"queued":{"summary":"queued","value":{"object":"sync","id":"sync_5d0c7a21-8e4b-4f6a-9c13-2b7e1a90d4f8","kind":"refresh","status":"queued","started_at":"2026-10-01T09:30:00.000Z","finished_at":null,"records_written":0,"error":null}}}}}},"400":{"description":"Error. Codes: unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"404":{"description":"Error. Codes: sync_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"queued","request":{"method":"GET","path":"/v1/syncs/{sync}"},"status":200}]}},"/v1/connect_links":{"post":{"operationId":"connect_links_create","tags":["Connect links"],"summary":"Create a connect link","description":"A single-use URL, valid for an hour, where a human pastes the provider credential so it never passes through the agent. The `url` is returned only now and cannot be read back; a replay with the same `Idempotency-Key` returns it from an encrypted store. Poll `GET /v1/connect_links/{id}` until `status` is `done`. A `label` another connection to the provider already has is a 409 `label_conflict`: a link never rotates an existing connection's credential. At most 10 unused links per project.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-mcp-key-types":["api","mcp"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 255 printable ASCII characters. A retry with the same key and body replays the first response (`Idempotent-Replayed: true`) for 24 hours; the same key with a different body is a 409, and so is a duplicate that arrives while the first request is still running.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The provider to connect, optionally pinning the credential type and a label.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectLinkCreateBody"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectLink"},"examples":{"millionverifier":{"summary":"millionverifier","value":{"object":"connect_link","id":"lnk_9a3f6c1e-2b84-4d7a-8e05-1c6b9d2f7a40","provider":"millionverifier","credential_type":null,"label":null,"status":"pending","connection":null,"expires_at":"2026-10-01T10:30:00.000Z","next_steps":[{"rel":"poll","method":"GET","href":"/v1/connect_links/lnk_9a3f6c1e-2b84-4d7a-8e05-1c6b9d2f7a40","why":"Poll until the status is done."}],"url":"https://argus.town/connect/argus_cl_3f1d9b7a5c2e4086a1b3d5f70e9c2a48b6d1f3e5a7c90214"}}}}}},"400":{"description":"Error. Codes: invalid_request_body, invalid_parameter, missing_parameter, invalid_idempotency_key, unknown_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"409":{"description":"Error. Codes: idempotency_key_reused, label_conflict, quota_exceeded, idempotency_key_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"413":{"description":"Error. Codes: payload_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"422":{"description":"Error. Codes: provider_not_connectable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not connectable":{"summary":"not connectable","value":{"error":{"type":"invalid_request","code":"provider_not_connectable","message":"Argus cannot poll \"nope\".","param":"provider","doc_url":"https://argus.town/docs/errors#provider_not_connectable","next_step":{"hint":"List providers Argus can poll.","method":"GET","href":"/v1/providers?connectable=true"},"request_id":null}}}}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"millionverifier","request":{"method":"POST","path":"/v1/connect_links","body":{"provider":"millionverifier"}},"status":201},{"name":"not connectable","request":{"method":"POST","path":"/v1/connect_links","body":{"provider":"nope"}},"status":422}]}},"/v1/connect_links/{id}":{"get":{"operationId":"connect_links_get","tags":["Connect links"],"summary":"Get a connect link","description":"Poll a link: `pending`, `submitting`, `done`, `expired` or `locked` (too many failed attempts). When `done`, `connection` is the new connection's id, or the object with `expand[]=connection`. The URL is not returned again.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-mcp-key-types":["api","mcp"],"parameters":[{"name":"id","in":"path","required":true,"description":"Link id, with or without the `lnk_` prefix.","schema":{"type":"string"}},{"name":"expand[]","in":"query","required":false,"description":"Fields to include. One or more of: connection.","schema":{"type":"array","items":{"type":"string","enum":["connection"]}},"style":"form","explode":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectLink"},"examples":{"waiting":{"summary":"waiting","value":{"object":"connect_link","id":"lnk_9a3f6c1e-2b84-4d7a-8e05-1c6b9d2f7a40","provider":"millionverifier","credential_type":null,"label":null,"status":"pending","connection":null,"expires_at":"2026-10-01T10:30:00.000Z","next_steps":[{"rel":"poll","method":"GET","href":"/v1/connect_links/lnk_9a3f6c1e-2b84-4d7a-8e05-1c6b9d2f7a40","why":"Poll until the status is done."}]}}}}}},"400":{"description":"Error. Codes: invalid_parameter, unknown_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"404":{"description":"Error. Codes: connect_link_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"waiting","request":{"method":"GET","path":"/v1/connect_links/{connect_link}"},"status":200}]}},"/v1/alert_rules":{"post":{"operationId":"alert_rules_create","tags":["Alerts"],"summary":"Create an alert rule","description":"Email the project's members when a connection crosses a threshold. `threshold` is USD, days or percent depending on `type`. `connections` lists the connections to watch; omit it to watch all of them. An id that is not a connection of the project is a 422, never a rule that silently watches everything. At most 100 rules per project.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 255 printable ASCII characters. A retry with the same key and body replays the first response (`Idempotent-Replayed: true`) for 24 hours; the same key with a different body is a 409, and so is a duplicate that arrives while the first request is still running.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The condition and what it watches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertRuleCreateBody"}}}},"responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertRule"},"examples":{"low balance":{"summary":"low balance","value":{"object":"alert_rule","id":"alr_2c8e5b13-7d4a-4f90-b6a1-3e9d0c7f5a82","type":"low_balance","threshold":10,"connections":["conn_0b6f2c1e-6c1d-4a39-9f43-5b0d2f7a8c11"],"enabled":true,"channel":"email","last_fired_at":null,"created_at":"2026-10-01T09:30:00.000Z"}}}}}},"400":{"description":"Error. Codes: invalid_request_body, invalid_parameter, missing_parameter, invalid_idempotency_key, unknown_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"409":{"description":"Error. Codes: idempotency_key_reused, quota_exceeded, idempotency_key_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"413":{"description":"Error. Codes: payload_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"422":{"description":"Error. Codes: connection_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unknown connection":{"summary":"unknown connection","value":{"error":{"type":"not_found","code":"connection_not_found","message":"No connection has the id conn_00000000-0000-0000-0000-000000000000 in this project.","param":"connections[0]","doc_url":"https://argus.town/docs/errors#connection_not_found","next_step":{"hint":"List this project's connections.","method":"GET","href":"/v1/connections"},"request_id":null}}}}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"low balance","request":{"method":"POST","path":"/v1/alert_rules","body":{"type":"low_balance","threshold":10,"connections":["{id}"]}},"status":201},{"name":"unknown connection","request":{"method":"POST","path":"/v1/alert_rules","body":{"type":"low_balance","threshold":10,"connections":["conn_00000000-0000-0000-0000-000000000000"]}},"status":422}]},"get":{"operationId":"alert_rules_list","tags":["Alerts"],"summary":"List alert rules","description":"The project's alert rules, newest first.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size. Default 25.","schema":{"$ref":"#/components/schemas/Int","description":"a number between 1 and 200","title":"between(1, 200)","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous page's `next_cursor`.","schema":{"$ref":"#/components/schemas/NonEmptyString"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertRuleList"},"examples":{"rules":{"summary":"rules","value":{"object":"list","data":[{"object":"alert_rule","id":"alr_2c8e5b13-7d4a-4f90-b6a1-3e9d0c7f5a82","type":"low_balance","threshold":10,"connections":["conn_0b6f2c1e-6c1d-4a39-9f43-5b0d2f7a8c11"],"enabled":true,"channel":"email","last_fired_at":null,"created_at":"2026-10-01T09:30:00.000Z"}],"has_more":false,"next_cursor":null}}}}}},"400":{"description":"Error. Codes: invalid_parameter, invalid_cursor, unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"rules","request":{"method":"GET","path":"/v1/alert_rules?limit=10"},"status":200}]}},"/v1/alert_rules/{id}":{"patch":{"operationId":"alert_rules_update","tags":["Alerts"],"summary":"Update an alert rule","description":"Change any of `type`, `threshold`, `connections` (`null` watches every connection) and `enabled`. Connection ids are checked like on creation.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api"],"parameters":[{"name":"id","in":"path","required":true,"description":"Rule id, with or without the `alr_` prefix.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 255 printable ASCII characters. A retry with the same key and body replays the first response (`Idempotent-Replayed: true`) for 24 hours; the same key with a different body is a 409, and so is a duplicate that arrives while the first request is still running.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"At least one field to change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertRuleUpdateBody"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertRule"},"examples":{"raise the threshold":{"summary":"raise the threshold","value":{"object":"alert_rule","id":"alr_2c8e5b13-7d4a-4f90-b6a1-3e9d0c7f5a82","type":"low_balance","threshold":25,"connections":["conn_0b6f2c1e-6c1d-4a39-9f43-5b0d2f7a8c11"],"enabled":true,"channel":"email","last_fired_at":null,"created_at":"2026-10-01T09:30:00.000Z"}}}}}},"400":{"description":"Error. Codes: invalid_request_body, invalid_parameter, invalid_idempotency_key, unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"empty connections":{"summary":"empty connections","value":{"error":{"type":"invalid_request","code":"invalid_parameter","message":"Invalid value for \"connections\": Expected an array of at least 1 item(s), actual []","param":"connections","doc_url":"https://argus.town/docs/errors#invalid_parameter","request_id":null}}}}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"404":{"description":"Error. Codes: alert_rule_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"409":{"description":"Error. Codes: idempotency_key_reused, idempotency_key_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"413":{"description":"Error. Codes: payload_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"422":{"description":"Error. Codes: connection_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"raise the threshold","request":{"method":"PATCH","path":"/v1/alert_rules/{alert_rule}","body":{"threshold":25}},"status":200},{"name":"empty connections","request":{"method":"PATCH","path":"/v1/alert_rules/{alert_rule}","body":{"connections":[]}},"status":400}]},"delete":{"operationId":"alert_rules_delete","tags":["Alerts"],"summary":"Delete an alert rule","description":"Session only: an API key is refused with `session_required`. Unknown ids are a 404.","security":[{"sessionCookie":[]}],"x-access":"session","parameters":[{"name":"id","in":"path","required":true,"description":"Rule id, with or without the `alr_` prefix.","schema":{"type":"string"}}],"responses":{"204":{"description":"Success. No content."},"400":{"description":"Error. Codes: unknown_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: session_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"api key refused":{"summary":"api key refused","value":{"error":{"type":"permission_error","code":"session_required","message":"This action needs a signed-in session in the Argus app. API keys cannot perform it.","param":null,"doc_url":"https://argus.town/docs/errors#session_required","next_step":{"hint":"Do this from the Argus app, signed in as a member of the project.","href":"https://argus.town/settings"},"request_id":null}}}}}}},"404":{"description":"Error. Codes: alert_rule_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"api key refused","request":{"method":"DELETE","path":"/v1/alert_rules/{alert_rule}"},"status":403,"credential":"api_key"},{"name":"delete","request":{"method":"DELETE","path":"/v1/alert_rules/{alert_rule}"},"status":204}]}},"/v1/alert_firings":{"get":{"operationId":"alert_firings_list","tags":["Alerts"],"summary":"List alert firings","description":"When rules fired, newest first. Filter with `rule` or `connection` (the same ids the objects carry).","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size. Default 25.","schema":{"$ref":"#/components/schemas/Int","description":"a number between 1 and 200","title":"between(1, 200)","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous page's `next_cursor`.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"rule","in":"query","required":false,"description":"Only firings of this rule (`alr_...`).","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"connection","in":"query","required":false,"description":"Only firings for this connection (`conn_...`).","schema":{"$ref":"#/components/schemas/NonEmptyString"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertFiringList"},"examples":{"none yet":{"summary":"none yet","value":{"object":"list","data":[],"has_more":false,"next_cursor":null}}}}}},"400":{"description":"Error. Codes: invalid_parameter, invalid_cursor, unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"none yet","request":{"method":"GET","path":"/v1/alert_firings?limit=10"},"status":200}]}},"/v1/negotiated_pricing/{provider}":{"put":{"operationId":"negotiated_pricing_put","tags":["Negotiated pricing"],"summary":"Set negotiated pricing","description":"Record what your deal with a provider costs, so spend is priced at your rates instead of list price. `rates` are set one per `sku` and `unit` (rates you do not list are kept); `plan` replaces the negotiated subscription, and fields you omit from it are cleared. Every entry is validated and one bad entry rejects the request with `param` naming it: nothing is skipped silently. Events from the last 7 days that were left unpriced are repriced. `provider` is any provider slug your events use, catalog or not. At most 500 rates and 100 plans per project. List rates are read-only (`GET /v1/negotiated_pricing/{provider}?expand[]=list_rates`); resetting to list price is done in the app.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api"],"parameters":[{"name":"provider","in":"path","required":true,"description":"Provider slug, for example `openrouter`.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 255 printable ASCII characters. A retry with the same key and body replays the first response (`Idempotent-Replayed: true`) for 24 hours; the same key with a different body is a 409, and so is a duplicate that arrives while the first request is still running.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Rates, a plan, or both.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegotiatedPricingBody"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegotiatedPricing"},"examples":{"one rate":{"summary":"one rate","value":{"object":"negotiated_pricing","provider":"openrouter","rates":[{"sku":"gpt-4o","unit":"input_tokens","nano_usd_per_unit":2000}],"plan":null,"updated_at":"2026-10-01T09:30:00.000Z"}}}}}},"400":{"description":"Error. Codes: invalid_request_body, invalid_parameter, invalid_idempotency_key, unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"malformed rate":{"summary":"malformed rate","value":{"error":{"type":"invalid_request","code":"invalid_parameter","message":"Invalid value for \"rates[0].nano_usd_per_unit\": Expected a number between 0 and 1000000000000, actual -1","param":"rates[0].nano_usd_per_unit","doc_url":"https://argus.town/docs/errors#invalid_parameter","request_id":null}}}}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"404":{"description":"Error. Codes: provider_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"409":{"description":"Error. Codes: idempotency_key_reused, quota_exceeded, idempotency_key_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"413":{"description":"Error. Codes: payload_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"one rate","request":{"method":"PUT","path":"/v1/negotiated_pricing/openrouter","body":{"rates":[{"sku":"gpt-4o","unit":"input_tokens","nano_usd_per_unit":2000}]}},"status":200},{"name":"malformed rate","request":{"method":"PUT","path":"/v1/negotiated_pricing/openrouter","body":{"rates":[{"sku":"gpt-4o","unit":"input_tokens","nano_usd_per_unit":-1}]}},"status":400}]},"get":{"operationId":"negotiated_pricing_get","tags":["Negotiated pricing"],"summary":"Get negotiated pricing","description":"The project's own rates and subscription for a provider; empty `rates` and a null `plan` when nothing is negotiated. `expand[]=list_rates` adds Argus's list rates, which negotiated rates replace one for one.","security":[{"bearerAuth":[]}],"x-access":"api_key","x-web":true,"x-mcp-key-types":["api"],"parameters":[{"name":"provider","in":"path","required":true,"description":"Provider slug, for example `openrouter`.","schema":{"type":"string"}},{"name":"expand[]","in":"query","required":false,"description":"Fields to include. One or more of: list_rates.","schema":{"type":"array","items":{"type":"string","enum":["list_rates"]}},"style":"form","explode":true}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegotiatedPricing"},"examples":{"negotiated":{"summary":"negotiated","value":{"object":"negotiated_pricing","provider":"openrouter","rates":[{"sku":"gpt-4o","unit":"input_tokens","nano_usd_per_unit":2000}],"plan":null,"updated_at":"2026-10-01T09:30:00.000Z"}}}}}},"400":{"description":"Error. Codes: invalid_parameter, unknown_parameter, missing_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"401":{"description":"Error. Codes: missing_credentials, invalid_api_key, session_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: key_type_not_allowed, session_required, csrf_check_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"404":{"description":"Error. Codes: provider_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"negotiated","request":{"method":"GET","path":"/v1/negotiated_pricing/openrouter"},"status":200}]},"delete":{"operationId":"negotiated_pricing_delete","tags":["Negotiated pricing"],"summary":"Reset to list pricing","description":"Remove every negotiated rate and the negotiated plan for a provider, or with `sku` and `unit` just that one rate (the plan stays). Session only: an API key is refused with `session_required`. A project with nothing negotiated, or no rate for that `sku` and `unit`, gets a 404.","security":[{"sessionCookie":[]}],"x-access":"session","parameters":[{"name":"provider","in":"path","required":true,"description":"Provider slug, for example `openrouter`.","schema":{"type":"string"}},{"name":"sku","in":"query","required":false,"description":"Reset only this rate; needs `unit`.","schema":{"$ref":"#/components/schemas/NonEmptyString"}},{"name":"unit","in":"query","required":false,"description":"The unit of the rate to reset; needs `sku`.","schema":{"$ref":"#/components/schemas/NonEmptyString"}}],"responses":{"204":{"description":"Success. No content."},"400":{"description":"Error. Codes: invalid_parameter, unknown_parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"403":{"description":"Error. Codes: session_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"api key refused":{"summary":"api key refused","value":{"error":{"type":"permission_error","code":"session_required","message":"This action needs a signed-in session in the Argus app. API keys cannot perform it.","param":null,"doc_url":"https://argus.town/docs/errors#session_required","next_step":{"hint":"Do this from the Argus app, signed in as a member of the project.","href":"https://argus.town/settings"},"request_id":null}}}}}}},"404":{"description":"Error. Codes: provider_not_found, negotiated_pricing_not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}},"429":{"description":"Error. Codes: rate_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Error. Codes: internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"api key refused","request":{"method":"DELETE","path":"/v1/negotiated_pricing/openrouter"},"status":403,"credential":"api_key"},{"name":"reset","request":{"method":"DELETE","path":"/v1/negotiated_pricing/openrouter"},"status":204}]}},"/v1/openapi.json":{"get":{"operationId":"openapi_get","tags":["Start"],"summary":"OpenAPI document","description":"This contract as OpenAPI 3.1, generated from the operation table.","security":[],"x-access":"public","parameters":[],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"},"examples":{}}}}},"x-argus-examples":[]}},"/v1/errors":{"get":{"operationId":"errors_list","tags":["Start"],"summary":"Error catalog","description":"Every error code the API returns, with its type and HTTP status.","security":[],"x-access":"public","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size. Default 25.","schema":{"$ref":"#/components/schemas/Int","description":"a number between 1 and 200","title":"between(1, 200)","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous page's `next_cursor`.","schema":{"$ref":"#/components/schemas/NonEmptyString"}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCodeList"},"examples":{"first code":{"summary":"first code","value":{"object":"list","data":[{"object":"error_code","code":"connection_not_found","type":"not_found","status":404,"description":"No connection with this id in the key's project.","doc_url":"https://argus.town/docs/errors#connection_not_found"}],"has_more":true,"next_cursor":"WyJjb25uZWN0aW9uX25vdF9mb3VuZCJd"}}}}}},"400":{"description":"Error. Codes: invalid_parameter, invalid_cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{}}}}},"x-argus-examples":[{"name":"first code","request":{"method":"GET","path":"/v1/errors?limit=1"},"status":200}]}}},"components":{"schemas":{"Advisory":{"type":"object","required":["level","code","message"],"properties":{"level":{"type":"string","enum":["info","warning","critical"]},"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true},"AlertFiring":{"type":"object","required":["object","id","rule","connection","fired_at","message","value","delivered","acknowledged"],"properties":{"object":{"type":"string","enum":["alert_firing"]},"id":{"type":"string"},"rule":{"type":"string"},"connection":{"anyOf":[{"type":"string"},{"type":"null"}]},"fired_at":{"type":"string","format":"date-time"},"message":{"type":"string"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]},"delivered":{"type":"boolean"},"acknowledged":{"type":"boolean"}},"additionalProperties":true},"AlertFiringList":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AlertFiring"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"AlertRule":{"type":"object","required":["object","id","type","threshold","connections","enabled","channel","last_fired_at","created_at"],"properties":{"object":{"type":"string","enum":["alert_rule"]},"id":{"type":"string"},"type":{"type":"string"},"threshold":{"type":"number"},"connections":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Connection ids the rule watches; `null` means every connection."},"enabled":{"type":"boolean"},"channel":{"type":"string","enum":["email"]},"last_fired_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":true},"AlertRuleCreateBody":{"type":"object","required":["type","threshold"],"properties":{"type":{"type":"string","enum":["low_balance","days_to_zero","spend_spike","projected_overage","rate_limit_headroom","error_rate","cost_drift"]},"threshold":{"type":"number","description":"USD, days or percent, depending on `type`.","title":"between(0, 1000000000000)","minimum":0,"maximum":1000000000000},"connections":{"type":"array","items":{"type":"string"},"description":"Connection ids the rule watches. Omit to watch every connection. An unknown id is an error.","title":"maxItems(50)","minItems":1,"maxItems":50},"enabled":{"type":"boolean"}},"additionalProperties":true},"AlertRuleList":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AlertRule"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"AlertRuleUpdateBody":{"type":"object","required":[],"properties":{"type":{"type":"string","enum":["low_balance","days_to_zero","spend_spike","projected_overage","rate_limit_headroom","error_rate","cost_drift"]},"threshold":{"type":"number","description":"a number between 0 and 1000000000000","title":"between(0, 1000000000000)","minimum":0,"maximum":1000000000000},"connections":{"anyOf":[{"type":"array","items":{"type":"string"},"description":"an array of at most 50 item(s)","title":"maxItems(50)","minItems":1,"maxItems":50},{"type":"null"}],"description":"`null` makes the rule watch every connection."},"enabled":{"type":"boolean"}},"additionalProperties":true},"ApiIndex":{"type":"object","required":["object","version","status","links","authentication","first_call","next_steps"],"properties":{"object":{"type":"string","enum":["api"]},"version":{"type":"string","enum":["v1"]},"status":{"type":"string","enum":["ok"]},"links":{"type":"object","required":["documentation","openapi","errors","providers","mcp"],"properties":{"documentation":{"type":"string"},"openapi":{"type":"string"},"errors":{"type":"string"},"providers":{"type":"string"},"mcp":{"type":"string"}},"additionalProperties":true},"authentication":{"type":"object","required":["scheme","key_type","create_key_url"],"properties":{"scheme":{"type":"string","enum":["bearer"]},"key_type":{"type":"string","enum":["api"]},"create_key_url":{"type":"string"}},"additionalProperties":true},"first_call":{"type":"object","required":["method","href","curl"],"properties":{"method":{"type":"string"},"href":{"type":"string"},"curl":{"type":"string"}},"additionalProperties":true},"next_steps":{"type":"array","items":{"$ref":"#/components/schemas/NextStepItem"}}},"additionalProperties":true},"BreakdownRow":{"type":"object","required":["period_start","dimension","dimension_key","spend_usd","requests","tokens"],"properties":{"period_start":{"type":"string","format":"date-time"},"dimension":{"type":"string"},"dimension_key":{"type":"string"},"spend_usd":{"type":"number"},"requests":{"type":"number"},"tokens":{"type":"number"}},"additionalProperties":true},"Connection":{"type":"object","required":["object","id","provider","origin","label","credential_type","status","status_detail","last_synced_at","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["connection"]},"id":{"type":"string"},"provider":{"type":"string"},"origin":{"type":"string","enum":["poll","push","both"]},"label":{"type":"string"},"credential_type":{"type":"string"},"status":{"type":"string"},"status_detail":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"metrics":{"$ref":"#/components/schemas/Metrics"},"metered":{"type":"boolean"},"advisories":{"type":"array","items":{"$ref":"#/components/schemas/Advisory"}},"usage":{"type":"array","items":{"$ref":"#/components/schemas/UsageDay"}},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownRow"}},"rate_limits":{"type":"array","items":{"$ref":"#/components/schemas/RateLimitReading"}},"sync_runs":{"type":"array","items":{"$ref":"#/components/schemas/Sync"}},"plan":{"anyOf":[{"$ref":"#/components/schemas/Plan"},{"type":"null"}]}},"additionalProperties":true},"ConnectionCreateBody":{"type":"object","required":["provider","secret"],"properties":{"provider":{"type":"string","description":"Provider slug from `GET /v1/providers?connectable=true`."},"credential_type":{"type":"string","description":"Defaults to the provider's first supported credential type."},"secret":{"type":"string","description":"The provider credential. Checked with the provider, stored encrypted, never returned.","title":"maxLength(8192)","minLength":1,"maxLength":8192},"label":{"type":"string","description":"a string at most 80 character(s) long","title":"maxLength(80)","pattern":"^\\S[\\s\\S]*\\S$|^\\S$|^$","minLength":1,"maxLength":80},"meta":{"type":"object","required":[],"properties":{},"additionalProperties":{"type":"string","description":"a string at most 200 character(s) long","title":"maxLength(200)","maxLength":200}}},"additionalProperties":true},"ConnectionList":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"ConnectionUpdateBody":{"type":"object","required":[],"properties":{"label":{"type":"string","description":"a string at most 80 character(s) long","title":"maxLength(80)","pattern":"^\\S[\\s\\S]*\\S$|^\\S$|^$","minLength":1,"maxLength":80},"secret":{"type":"string","description":"A replacement credential. Checked with the provider before it is stored. `credential_type` and `meta` change only together with it.","title":"maxLength(8192)","minLength":1,"maxLength":8192},"credential_type":{"type":"string"},"meta":{"type":"object","required":[],"properties":{},"additionalProperties":{"type":"string","description":"a string at most 200 character(s) long","title":"maxLength(200)","maxLength":200}}},"additionalProperties":true},"ConnectLink":{"type":"object","required":["object","id","provider","credential_type","label","status","connection","expires_at","next_steps"],"properties":{"object":{"type":"string","enum":["connect_link"]},"id":{"type":"string"},"provider":{"type":"string"},"credential_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["pending","submitting","done","expired","locked"]},"connection":{"anyOf":[{"type":"string"},{"$ref":"#/components/schemas/Connection"},{"type":"null"}],"description":"The connection once the human has pasted the credential (`done`): its id, or the object with `expand[]=connection`."},"url":{"type":"string","description":"Where the human pastes the credential. Returned only when the link is created; it cannot be read back."},"expires_at":{"type":"string","format":"date-time"},"next_steps":{"type":"array","items":{"$ref":"#/components/schemas/NextStepItem"}}},"additionalProperties":true},"ConnectLinkCreateBody":{"type":"object","required":["provider"],"properties":{"provider":{"type":"string"},"credential_type":{"type":"string"},"label":{"type":"string","description":"a string at most 60 character(s) long","title":"maxLength(60)","pattern":"^\\S[\\s\\S]*\\S$|^\\S$|^$","minLength":1,"maxLength":60}},"additionalProperties":true},"DeviceCode":{"type":"object","required":["object","device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval"],"properties":{"object":{"type":"string","enum":["device_code"]},"device_code":{"type":"string"},"user_code":{"type":"string"},"verification_uri":{"type":"string"},"verification_uri_complete":{"type":"string"},"expires_in":{"type":"number"},"interval":{"type":"number"}},"additionalProperties":true},"DeviceCodeBody":{"type":"object","required":[],"properties":{"client_name":{"type":"string","description":"a string at most 60 character(s) long","title":"maxLength(60)","minLength":1,"maxLength":60},"scopes":{"type":"array","items":{"type":"string","enum":["api","read","ingest","mcp"]},"description":"`api` (alias `read`): an API key; `ingest`: a telemetry source; `mcp`: an MCP key. Default: `api` and `ingest`.","title":"maxItems(4)","minItems":1,"maxItems":4}},"additionalProperties":true},"DeviceToken":{"type":"object","required":["object","status","next_steps"],"properties":{"object":{"type":"string","enum":["device_token"]},"status":{"type":"string","enum":["pending","approved","denied","consumed","expired","invalid"]},"project":{"type":"object","required":["object","id","name"],"properties":{"object":{"type":"string","enum":["project"]},"id":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"api_key":{"type":"string"},"mcp_key":{"type":"string"},"source":{"type":"object","required":["object","id","secret"],"properties":{"object":{"type":"string","enum":["source"]},"id":{"type":"string"},"secret":{"type":"string"}},"additionalProperties":true},"next_steps":{"type":"array","items":{"$ref":"#/components/schemas/NextStepItem"}}},"additionalProperties":true},"DeviceTokenBody":{"type":"object","required":["device_code"],"properties":{"device_code":{"type":"string","description":"a string at most 200 character(s) long","title":"maxLength(200)","minLength":1,"maxLength":200}},"additionalProperties":true},"ErrorCodeInfo":{"type":"object","required":["object","code","type","status","description","doc_url"],"properties":{"object":{"type":"string","enum":["error_code"]},"code":{"type":"string"},"type":{"type":"string"},"status":{"type":"number"},"description":{"type":"string"},"doc_url":{"type":"string"}},"additionalProperties":true},"ErrorCodeList":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ErrorCodeInfo"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message","param","doc_url","request_id"],"properties":{"type":{"type":"string","enum":["invalid_request","authentication_error","permission_error","not_found","conflict","rate_limited","plan_limit","upstream_error","api_error"]},"code":{"type":"string","enum":["unknown_parameter","invalid_parameter","invalid_cursor","method_not_allowed","missing_credentials","invalid_api_key","invalid_request_body","missing_parameter","invalid_idempotency_key","payload_too_large","too_many_events","no_valid_events","missing_source_credentials","invalid_source_credentials","timestamp_stale","idempotency_key_reused","idempotency_key_in_progress","too_many_auth_failures","origin_not_allowed","key_type_not_allowed","not_found","provider_not_found","connection_not_found","sync_not_found","connect_link_not_found","alert_rule_not_found","negotiated_pricing_not_found","provider_not_connectable","credential_invalid","provider_unreachable","label_conflict","connection_not_pollable","quota_exceeded","session_required","session_expired","csrf_check_failed","rate_limit_exceeded","internal_error"]},"message":{"type":"string"},"param":{"anyOf":[{"type":"string"},{"type":"null"}]},"doc_url":{"type":"string"},"next_step":{"$ref":"#/components/schemas/NextStep"},"details":{"type":"object","required":[],"properties":{},"additionalProperties":{"$id":"/schemas/unknown","title":"unknown"}},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true}},"additionalProperties":true},"Event":{"type":"object","required":["object","id","source","connection","provider","hostname","endpoint","method","model","status","latency_ms","units","metadata","cost_usd","cost_micros","cost_provenance","price_match","provider_request_id","credits_spent","credits_remaining","occurred_at","received_at"],"properties":{"object":{"type":"string","enum":["event"]},"id":{"type":"string"},"source":{"type":"string"},"connection":{"anyOf":[{"type":"string"},{"type":"null"}]},"provider":{"anyOf":[{"type":"string"},{"type":"null"}]},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}]},"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}]},"method":{"anyOf":[{"type":"string"},{"type":"null"}]},"model":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"number"},{"type":"null"}]},"latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}]},"units":{"anyOf":[{"type":"object","required":[],"properties":{},"additionalProperties":{"type":"number"}},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","required":[],"properties":{},"additionalProperties":{"type":"string"}},{"type":"null"}]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}]},"cost_micros":{"anyOf":[{"type":"number"},{"type":"null"}]},"cost_provenance":{"type":"string","enum":["provider_reported","app_reported","derived","unpriced"]},"price_match":{"anyOf":[{"type":"string"},{"type":"null"}]},"provider_request_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"credits_spent":{"anyOf":[{"type":"number"},{"type":"null"}]},"credits_remaining":{"anyOf":[{"type":"number"},{"type":"null"}]},"occurred_at":{"type":"string","format":"date-time"},"received_at":{"type":"string","format":"date-time"}},"additionalProperties":true},"EventBatch":{"type":"object","required":["object","accepted","rejected","rejected_count","warnings","warnings_count","events","connections","next_steps"],"properties":{"object":{"type":"string","enum":["event_batch"]},"accepted":{"type":"number"},"rejected":{"type":"array","items":{"$ref":"#/components/schemas/EventRejection"},"description":"The first 100 rejections; `rejected_count` is the total."},"rejected_count":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/EventWarning"},"description":"The first 100 warnings; `warnings_count` is the total."},"warnings_count":{"type":"number"},"events":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}},"additionalProperties":true},"description":"Ids of the queued events, in request order. Read them back with `GET /v1/events?id=`."},"connections":{"type":"array","items":{"type":"object","required":["id","provider","created"],"properties":{"id":{"type":"string"},"provider":{"type":"string"},"created":{"type":"boolean"}},"additionalProperties":true},"description":"Connections the batch attached to; `created` when this batch made one."},"next_steps":{"type":"array","items":{"$ref":"#/components/schemas/NextStepItem"}}},"additionalProperties":true},"EventInput":{"type":"object","required":[],"properties":{"id":{"type":"string","description":"Your id for this event, 16 to 64 characters, unique per source. Re-sending an id is a no-op. Omit it and Argus mints an `evt_` id."},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Provider slug, for example `openai`. Derived from `hostname` when omitted."},"hostname":{"type":"string"},"connection":{"type":"string","description":"Attribute the event to this connection (`conn_...`). It must exist in the project."},"endpoint":{"type":"string"},"method":{"type":"string"},"model":{"type":"string"},"operation":{"type":"string"},"cost_usd":{"type":"number","description":"What the call cost. Omit it and Argus prices the event from `model` and `units`."},"cost_provenance":{"type":"string","enum":["provider_reported","app_reported"]},"provider_request_id":{"type":"string"},"units":{"type":"object","required":[],"properties":{},"additionalProperties":{"type":"number"},"description":"For example `input_tokens`, `output_tokens`, `requests`, `credits`."},"tokens_input":{"type":"number"},"tokens_output":{"type":"number"},"requests":{"type":"number"},"status":{"type":"number"},"latency_ms":{"type":"number"},"credits_spent":{"type":"number"},"credits_remaining":{"type":"number"},"metadata":{"type":"object","required":[],"properties":{},"additionalProperties":{"type":"string"}},"occurred_at":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"ISO 8601 string or epoch milliseconds. Defaults to receipt time."},"rate_limit":{"$ref":"#/components/schemas/RateLimitInput"},"rate_limits":{"type":"array","items":{"$ref":"#/components/schemas/RateLimitInput"}},"pricing_override":{"type":"object","required":["rates"],"properties":{"rates":{"type":"array","items":{"type":"object","required":["unit","nano_usd_per_unit"],"properties":{"unit":{"type":"string"},"nano_usd_per_unit":{"type":"number"},"sku":{"type":"string"}},"additionalProperties":true}}},"additionalProperties":true}},"additionalProperties":true},"EventList":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"EventRejection":{"type":"object","required":["index","id","code","message"],"properties":{"index":{"type":"number"},"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"code":{"type":"string","enum":["invalid_event","event_too_large","invalid_event_id","duplicate_id","outside_backfill_window","unknown_connection","connection_limit"]},"message":{"type":"string"}},"additionalProperties":true},"EventsBody":{"type":"object","required":["events"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/EventInput"}},"backfill":{"type":"boolean","description":"Allow `occurred_at` up to 29 days back. Older events are rejected."}},"additionalProperties":true},"EventValidation":{"type":"object","required":["object","valid","accepted","rejected","rejected_count","warnings","warnings_count","normalized_events","next_steps"],"properties":{"object":{"type":"string","enum":["event_validation"]},"valid":{"type":"boolean"},"accepted":{"type":"number"},"rejected":{"type":"array","items":{"$ref":"#/components/schemas/EventRejection"},"description":"The first 100 rejections; `rejected_count` is the total."},"rejected_count":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/EventWarning"},"description":"The first 100 warnings; `warnings_count` is the total."},"warnings_count":{"type":"number"},"normalized_events":{"type":"array","items":{"$ref":"#/components/schemas/EventInput"},"description":"The accepted events as `POST /v1/events` would store them. Send them back as-is."},"next_steps":{"type":"array","items":{"$ref":"#/components/schemas/NextStepItem"}}},"additionalProperties":true},"EventWarning":{"type":"object","required":["index","code","field","message"],"properties":{"index":{"anyOf":[{"type":"number"},{"type":"null"}]},"code":{"type":"string","enum":["unknown_field","occurred_at_clamped","provider_unresolved"]},"field":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"type":"string"}},"additionalProperties":true},"Int":{"type":"integer","description":"an integer","title":"int"},"ListRate":{"type":"object","required":["sku","unit","nano_usd_per_unit","source"],"properties":{"sku":{"type":"string","description":"a string at most 120 character(s) long","title":"maxLength(120)","minLength":1,"maxLength":120},"unit":{"type":"string","description":"a string at most 60 character(s) long","title":"maxLength(60)","minLength":1,"maxLength":60},"nano_usd_per_unit":{"type":"integer","description":"a number between 0 and 1000000000000","title":"between(0, 1000000000000)","minimum":0,"maximum":1000000000000},"source":{"type":"string"}},"additionalProperties":true},"Metrics":{"type":"object","required":["balance_usd","burn_per_day","days_to_zero","mtd_spend_usd","spend_basis","observed_since","balance_scope","projected_month_end_usd","wow_change_pct","rate_limit_headroom_pct","error_rate_pct","accuracy","cost_drift_pct","billing_mode","utilization_pct","used_amount","included_amount","included_meter_id","subscription_fee_usd","effective_usd_per_unit","days_to_reset","recommended_action","recommended_tier","recommended_delta_usd"],"properties":{"balance_usd":{"anyOf":[{"type":"number"},{"type":"null"}]},"burn_per_day":{"type":"number"},"days_to_zero":{"anyOf":[{"type":"number"},{"type":"null"}]},"mtd_spend_usd":{"type":"number"},"spend_basis":{"type":"string","enum":["reported","observed_since_connected"]},"observed_since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"balance_scope":{"type":"string","enum":["account","key","unknown"]},"projected_month_end_usd":{"type":"number"},"wow_change_pct":{"anyOf":[{"type":"number"},{"type":"null"}]},"rate_limit_headroom_pct":{"anyOf":[{"type":"number"},{"type":"null"}]},"error_rate_pct":{"anyOf":[{"type":"number"},{"type":"null"}]},"accuracy":{"anyOf":[{"type":"string"},{"type":"null"}]},"cost_drift_pct":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing_mode":{"anyOf":[{"type":"string"},{"type":"null"}]},"utilization_pct":{"anyOf":[{"type":"number"},{"type":"null"}]},"used_amount":{"anyOf":[{"type":"number"},{"type":"null"}]},"included_amount":{"anyOf":[{"type":"number"},{"type":"null"}]},"included_meter_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"subscription_fee_usd":{"anyOf":[{"type":"number"},{"type":"null"}]},"effective_usd_per_unit":{"anyOf":[{"type":"number"},{"type":"null"}]},"days_to_reset":{"anyOf":[{"type":"number"},{"type":"null"}]},"recommended_action":{"anyOf":[{"type":"string"},{"type":"null"}]},"recommended_tier":{"anyOf":[{"type":"string"},{"type":"null"}]},"recommended_delta_usd":{"anyOf":[{"type":"number"},{"type":"null"}]},"right_sizing":{"anyOf":[{"$ref":"#/components/schemas/RightSizing"},{"type":"null"}],"description":"The full recommendation behind the `recommended_*` fields. Present only on `GET /v1/connections/{id}` with `expand[]=metrics`."}},"additionalProperties":true},"NegotiatedPlan":{"type":"object","required":["price_usd_micros","included_amount","included_meter_id","overage_nano_usd_per_unit"],"properties":{"price_usd_micros":{"anyOf":[{"type":"integer","description":"a number between 0 and 1000000000000","title":"between(0, 1000000000000)","minimum":0,"maximum":1000000000000},{"type":"null"}]},"included_amount":{"anyOf":[{"type":"integer","description":"a number between 0 and 1000000000000000","title":"between(0, 1000000000000000)","minimum":0,"maximum":1000000000000000},{"type":"null"}]},"included_meter_id":{"anyOf":[{"type":"string","description":"a string at most 120 character(s) long","title":"maxLength(120)","minLength":1,"maxLength":120},{"type":"null"}]},"overage_nano_usd_per_unit":{"anyOf":[{"type":"integer","description":"a number between 0 and 1000000000000","title":"between(0, 1000000000000)","minimum":0,"maximum":1000000000000},{"type":"null"}]}},"additionalProperties":true},"NegotiatedPlanInput":{"type":"object","required":[],"properties":{"price_usd_micros":{"type":"integer","description":"a number between 0 and 1000000000000","title":"between(0, 1000000000000)","minimum":0,"maximum":1000000000000},"included_amount":{"type":"integer","description":"a number between 0 and 1000000000000000","title":"between(0, 1000000000000000)","minimum":0,"maximum":1000000000000000},"included_meter_id":{"type":"string","description":"a string at most 120 character(s) long","title":"maxLength(120)","minLength":1,"maxLength":120},"overage_nano_usd_per_unit":{"type":"integer","description":"a number between 0 and 1000000000000","title":"between(0, 1000000000000)","minimum":0,"maximum":1000000000000}},"additionalProperties":true,"description":"The negotiated subscription. Fields you omit are cleared."},"NegotiatedPricing":{"type":"object","required":["object","provider","rates","plan","updated_at"],"properties":{"object":{"type":"string","enum":["negotiated_pricing"]},"provider":{"type":"string"},"rates":{"type":"array","items":{"$ref":"#/components/schemas/NegotiatedRate"}},"plan":{"anyOf":[{"$ref":"#/components/schemas/NegotiatedPlan"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"list_rates":{"type":"array","items":{"$ref":"#/components/schemas/ListRate"},"description":"Argus's list rate for each `sku` and `unit` the provider is priced by, so you can see what a negotiated rate replaces. Present only with `expand[]=list_rates`."}},"additionalProperties":true},"NegotiatedPricingBody":{"type":"object","required":[],"properties":{"rates":{"type":"array","items":{"$ref":"#/components/schemas/NegotiatedRate"},"description":"Rates to set, one per `sku` and `unit`; rates already set and not listed are kept. One bad entry rejects the whole request.","title":"maxItems(100)","minItems":1,"maxItems":100},"plan":{"$ref":"#/components/schemas/NegotiatedPlanInput"}},"additionalProperties":true},"NegotiatedRate":{"type":"object","required":["sku","unit","nano_usd_per_unit"],"properties":{"sku":{"type":"string","description":"a string at most 120 character(s) long","title":"maxLength(120)","minLength":1,"maxLength":120},"unit":{"type":"string","description":"a string at most 60 character(s) long","title":"maxLength(60)","minLength":1,"maxLength":60},"nano_usd_per_unit":{"type":"integer","description":"a number between 0 and 1000000000000","title":"between(0, 1000000000000)","minimum":0,"maximum":1000000000000}},"additionalProperties":true},"NextStep":{"type":"object","required":["hint"],"properties":{"hint":{"type":"string"},"method":{"type":"string"},"href":{"type":"string"}},"additionalProperties":true},"NextStepItem":{"type":"object","required":["rel","method","href","why"],"properties":{"rel":{"type":"string"},"method":{"type":"string"},"href":{"type":"string"},"why":{"type":"string"}},"additionalProperties":true},"NonEmptyString":{"type":"string","description":"a non empty string","title":"nonEmptyString","minLength":1},"OpenApiDocument":{"type":"object","required":[],"properties":{},"additionalProperties":{"$id":"/schemas/unknown","title":"unknown"},"description":"An OpenAPI 3.1 document."},"Plan":{"type":"object","required":["object","id","plan_name","tier","rate_limit_tier","in_overage","price_usd","included_meter_id","included_amount","included_period","used_this_period","period_reset_at","rollover","source","captured_at"],"properties":{"object":{"type":"string","enum":["plan"]},"id":{"type":"string"},"plan_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"tier":{"anyOf":[{"type":"string"},{"type":"null"}]},"rate_limit_tier":{"anyOf":[{"type":"string"},{"type":"null"}]},"in_overage":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"price_usd":{"anyOf":[{"type":"number"},{"type":"null"}]},"included_meter_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"included_amount":{"anyOf":[{"type":"number"},{"type":"null"}]},"included_period":{"anyOf":[{"type":"string"},{"type":"null"}]},"used_this_period":{"anyOf":[{"type":"number"},{"type":"null"}]},"period_reset_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"rollover":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"captured_at":{"type":"string","format":"date-time"}},"additionalProperties":true},"Project":{"type":"object","required":["object","id","name","created_at","key","permissions","plan","next_steps"],"properties":{"object":{"type":"string","enum":["project"]},"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"key":{"type":"object","required":["object","id","type","name","prefix"],"properties":{"object":{"type":"string","enum":["key"]},"id":{"type":"string"},"type":{"type":"string","enum":["api"]},"name":{"type":"string"},"prefix":{"type":"string"}},"additionalProperties":true},"permissions":{"type":"array","items":{"type":"string"},"description":"Operation ids this key may call."},"plan":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}},"additionalProperties":true},"next_steps":{"type":"array","items":{"$ref":"#/components/schemas/NextStepItem"}}},"additionalProperties":true},"Provider":{"type":"object","required":["object","id","pricing_model","summary","connectable","credential_types","offering"],"properties":{"object":{"type":"string","enum":["provider"]},"id":{"type":"string"},"pricing_model":{"type":"string"},"summary":{"type":"string"},"connectable":{"type":"boolean"},"credential_types":{"type":"array","items":{"type":"string"}},"offering":{"type":"object","required":[],"properties":{},"additionalProperties":{"$id":"/schemas/unknown","title":"unknown"}}},"additionalProperties":true},"ProviderList":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProviderSummary"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"ProviderSummary":{"type":"object","required":["object","id","pricing_model","summary","connectable","credential_types"],"properties":{"object":{"type":"string","enum":["provider"]},"id":{"type":"string"},"pricing_model":{"type":"string"},"summary":{"type":"string"},"connectable":{"type":"boolean"},"credential_types":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"RateLimitInput":{"type":"object","required":[],"properties":{"limit_type":{"type":"string","enum":["rpm","tpm","credits"]},"limit":{"type":"number"},"remaining":{"type":"number"},"reset_at":{"type":"number","description":"Epoch milliseconds."}},"additionalProperties":true},"RateLimitReading":{"type":"object","required":["limit_type","limit","remaining","reset_at","observed_at"],"properties":{"limit_type":{"type":"string"},"limit":{"anyOf":[{"type":"number"},{"type":"null"}]},"remaining":{"anyOf":[{"type":"number"},{"type":"null"}]},"reset_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"observed_at":{"type":"string","format":"date-time"}},"additionalProperties":true},"RightSizing":{"type":"object","required":["action","target_plan_id","target_plan_name","delta_usd_monthly","basis_pct","reason"],"properties":{"action":{"type":"string","enum":["hold","downgrade","upgrade","buy_pack"]},"target_plan_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"target_plan_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta_usd_monthly":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Monthly cost change versus the current plan; negative is savings."},"basis_pct":{"type":"number"},"reason":{"type":"string"}},"additionalProperties":true},"Spend":{"type":"object","required":["object","since","until","granularity","group_by","totals","series","next_steps"],"properties":{"object":{"type":"string","enum":["spend"]},"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"granularity":{"type":"string","enum":["day"]},"group_by":{"anyOf":[{"type":"string","enum":["provider","connection","model"]},{"type":"null"}]},"totals":{"$ref":"#/components/schemas/SpendTotals"},"series":{"type":"array","items":{"$ref":"#/components/schemas/SpendDay"}},"next_steps":{"type":"array","items":{"$ref":"#/components/schemas/NextStepItem"}}},"additionalProperties":true},"SpendDay":{"type":"object","required":["period_start","spend_usd","requests","groups"],"properties":{"period_start":{"type":"string","format":"date-time"},"spend_usd":{"type":"number"},"requests":{"type":"number"},"groups":{"type":"array","items":{"type":"object","required":["key","spend_usd","requests"],"properties":{"key":{"type":"string"},"spend_usd":{"type":"number"},"requests":{"type":"number"}},"additionalProperties":true}}},"additionalProperties":true},"SpendTotals":{"type":"object","required":["spend_usd","requests","tokens_input","tokens_output","errors"],"properties":{"spend_usd":{"type":"number"},"requests":{"type":"number"},"tokens_input":{"type":"number"},"tokens_output":{"type":"number"},"errors":{"type":"number"}},"additionalProperties":true},"Summary":{"type":"object","required":["object","totals","connections","advisories","next_steps"],"properties":{"object":{"type":"string","enum":["summary"]},"totals":{"type":"object","required":["mtd_spend_usd","projected_month_end_usd"],"properties":{"mtd_spend_usd":{"type":"number"},"projected_month_end_usd":{"type":"number"}},"additionalProperties":true},"connections":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}},"advisories":{"type":"array","items":{"type":"object","required":["connection","level","code","message"],"properties":{"connection":{"type":"string"},"level":{"type":"string","enum":["info","warning","critical"]},"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":true}},"next_steps":{"type":"array","items":{"$ref":"#/components/schemas/NextStepItem"}}},"additionalProperties":true},"Sync":{"type":"object","required":["object","id","kind","status","started_at","finished_at","records_written","error"],"properties":{"object":{"type":"string","enum":["sync"]},"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"records_written":{"type":"number"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"SyncList":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Sync"}},"has_more":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"UsageDay":{"type":"object","required":["period_start","spend_usd","requests","tokens_input","tokens_output","errors","preliminary"],"properties":{"period_start":{"type":"string","format":"date-time"},"spend_usd":{"type":"number"},"requests":{"type":"number"},"tokens_input":{"type":"number"},"tokens_output":{"type":"number"},"errors":{"type":"number"},"preliminary":{"type":"boolean"}},"additionalProperties":true}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An `api` key."},"sessionCookie":{"type":"apiKey","in":"cookie","name":"argus_session","description":"The signed-in web app session. Operations that need it refuse every API key with `session_required`."},"sourceSecret":{"type":"http","scheme":"bearer","description":"A source secret (`argus_src_...`), sent with the `Argus-Source` header. Write-only: it can send events and read nothing."},"sourceSignature":{"type":"apiKey","in":"header","name":"X-Argus-Signature","description":"Hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the source secret, sent with `X-Argus-Source` and `X-Argus-Timestamp` (epoch ms, within 5 minutes)."}}},"x-error-codes":{"unknown_parameter":{"type":"invalid_request","status":400,"description":"The request has a query parameter this endpoint does not accept."},"invalid_parameter":{"type":"invalid_request","status":400,"description":"A parameter has a value this endpoint cannot use. `param` names it."},"invalid_cursor":{"type":"invalid_request","status":400,"description":"The cursor is malformed or does not belong to this list. Start again without it."},"method_not_allowed":{"type":"invalid_request","status":405,"description":"The path exists but not for this HTTP method. The Allow header lists the methods."},"missing_credentials":{"type":"authentication_error","status":401,"description":"No Authorization header was sent."},"invalid_api_key":{"type":"authentication_error","status":401,"description":"The key is unknown, revoked, or not an API key."},"invalid_request_body":{"type":"invalid_request","status":400,"description":"The body is not a JSON object (or, on `/v1/events`, not an event or an `events` array), or it is empty where fields are required."},"missing_parameter":{"type":"invalid_request","status":400,"description":"A required body field or header is missing. `param` names it."},"invalid_idempotency_key":{"type":"invalid_request","status":400,"description":"The Idempotency-Key header must be 1 to 255 printable ASCII characters."},"payload_too_large":{"type":"invalid_request","status":413,"description":"The body is over 1,000,000 bytes. Split the batch."},"too_many_events":{"type":"invalid_request","status":413,"description":"A batch holds at most 1,000 events. Split it."},"no_valid_events":{"type":"invalid_request","status":422,"description":"Every event in the batch was rejected, so nothing was queued. Send the same body to `POST /v1/events/validate` for each event's reason."},"missing_source_credentials":{"type":"authentication_error","status":401,"description":"No source credential was sent. Use `Authorization: Bearer <source secret>` with `Argus-Source: <source id>`, or the HMAC headers `X-Argus-Source`, `X-Argus-Timestamp` and `X-Argus-Signature`."},"invalid_source_credentials":{"type":"authentication_error","status":401,"description":"The source is unknown or revoked, or the bearer secret or HMAC signature is wrong (sign the timestamp, a dot and the raw body, hex HMAC-SHA256). The cases are not distinguished."},"timestamp_stale":{"type":"authentication_error","status":401,"description":"The signed timestamp (epoch milliseconds) is more than 5 minutes from server time."},"idempotency_key_reused":{"type":"conflict","status":409,"description":"This Idempotency-Key was already used with a different request body or source. Use a new key for a new request."},"idempotency_key_in_progress":{"type":"conflict","status":409,"description":"A request with this Idempotency-Key is still running. Retry with the same key after a moment; it replays the response once the first request finishes."},"too_many_auth_failures":{"type":"rate_limited","status":429,"description":"Too many failed authentication attempts from this address. Wait `Retry-After` seconds. Valid credentials keep working from an address over budget, except that a credential the server has not seen recently gets only a small number of lookups per window, tracked per server instance; a client sharing an address with an attacker can be briefly locked out."},"origin_not_allowed":{"type":"permission_error","status":403,"description":"A browser Origin that is not allow-listed called the MCP server. Non-browser clients send no Origin."},"key_type_not_allowed":{"type":"permission_error","status":403,"description":"This key's type cannot call this endpoint."},"not_found":{"type":"not_found","status":404,"description":"No such endpoint."},"provider_not_found":{"type":"not_found","status":404,"description":"No provider has this slug."},"connection_not_found":{"type":"not_found","status":404,"description":"No connection with this id in the key's project. When a request body names the connection (`param` says where) the status is 422."},"sync_not_found":{"type":"not_found","status":404,"description":"No sync with this id in the key's project."},"connect_link_not_found":{"type":"not_found","status":404,"description":"No connect link with this id in the key's project."},"alert_rule_not_found":{"type":"not_found","status":404,"description":"No alert rule with this id in the key's project."},"negotiated_pricing_not_found":{"type":"not_found","status":404,"description":"The project has no negotiated pricing for this provider."},"provider_not_connectable":{"type":"invalid_request","status":422,"description":"The provider is unknown or Argus cannot poll it with a credential (telemetry only)."},"credential_invalid":{"type":"invalid_request","status":422,"description":"The provider rejected the credential. `message` carries the provider's reason; the credential is never echoed."},"provider_unreachable":{"type":"upstream_error","status":502,"description":"Argus could not reach the provider to check the credential. Retry."},"label_conflict":{"type":"conflict","status":409,"description":"Another connection to this provider already has this label. Update that connection instead, or choose another label."},"connection_not_pollable":{"type":"conflict","status":409,"description":"The connection has no credential to poll with (telemetry only) or is suspended, so there is nothing to sync."},"quota_exceeded":{"type":"plan_limit","status":409,"description":"The project reached a limit on this kind of resource. `details` holds `resource`, `limit` and `used`."},"session_required":{"type":"permission_error","status":403,"description":"This operation needs a signed-in session in the Argus app; API keys cannot perform it."},"session_expired":{"type":"authentication_error","status":401,"description":"The web app's session is missing, expired or signed out. Only the signed-in web app sees it."},"csrf_check_failed":{"type":"permission_error","status":403,"description":"A web-app write did not come from the app itself: it lacks `x-argus-csrf`, or its `Origin` or `Sec-Fetch-Site` is not the app's. API keys never see it."},"rate_limit_exceeded":{"type":"rate_limited","status":429,"description":"The key exceeded its request budget. Wait `Retry-After` seconds."},"internal_error":{"type":"api_error","status":500,"description":"Something failed on our side. Retry; quote `request_id` if it persists."}}}