argus-town Providers API

openapi: 3.2.0
info:
  title: Argus Providers API
  version: '1'
  description: 'Argus API v1: spend, balances and rate-limit headroom across the APIs you pay for.

    Authenticate reads with an `api` key as `Authorization: Bearer `. Every key sees one project.

    Operations marked `x-access: session` are for the signed-in web app; API keys get `session_required`.

    Operations marked `x-web: true` also accept the web app''s session, which API clients never use.

    Operations with `x-mcp-key-types` are also MCP tools of the same name at `POST https://mcp.argus.town`, for keys of those types.

    Send 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.

    Responses are bare resources with an `object` tag; lists are `{object: "list", data, has_more, next_cursor}`.

    Errors are `{error: {type, code, message, param, doc_url, next_step, request_id}}` with real HTTP statuses.

    Unknown query parameters are rejected. Ids are prefixed (`conn_...`); bare ids are accepted on input.

    Within v1 changes are additive: ignore fields you do not recognise.'
servers:
- url: https://api.argus.town
tags:
- name: Providers
paths:
  /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
components:
  schemas:
    NextStep:
      type: object
      required:
      - hint
      properties:
        hint:
          type: string
        method:
          type: string
        href:
          type: string
      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
    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
    Int:
      type: integer
      description: an integer
      title: int
    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
    NonEmptyString:
      type: string
      description: a non empty string
      title: nonEmptyString
      minLength: 1
  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.