Everyn Usage API

openapi: 3.2.0
info:
  description: 'everyn self-serve API for dataset upload sessions, job specs, managed runs, run inspection, retry lineage, exports, alerts, webhooks, model catalog reads, usage and managed-AI balance reads, and organization administration.


    API routes use the `/v1` prefix. API-key product calls use `Authorization: Bearer sk-everyn-...` and derive organization context from the key. Job creation, editing and forking require a human browser session and CSRF protection; product API keys may read and run saved jobs but cannot author them. Browser-admin organization routes use bearer credentials and organization IDs in the route. Successful list responses use `{ "data": [], "nextCursor": null }`, and every response includes `X-Request-Id`.'
  title: everyn Public Usage API
  version: 1.0.0
servers:
- description: Production API
  url: https://api.everyn.ai
- description: Local development API
  url: http://localhost:8000
tags:
- description: 'Organization usage and funding reads: the browser workspace usage snapshot and the machine-readable managed-AI balance preflight (runs:read). The execution-safe balance is advisory — settlement drains asynchronously after runs complete.'
  name: Usage
paths:
  /v1/organizations/{organization_id}/usage:
    get:
      description: Get Workspace Usage. Browser-admin Everyn operation. Send the request to the selected server from this document with a human principal bearer token. Product API keys cannot call this route. Parameters and responses are typed in this document.
      operationId: get_workspace_usage_v1_organizations__organization_id__usage_get
      parameters:
      - description: Everyn organization that owns this resource.
        in: path
        name: organization_id
        required: true
        schema:
          title: Organization Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/WorkspaceUsageResponse'
                - $ref: '#/components/schemas/WorkspaceUsageUnavailableResponse'
                title: Response Get Workspace Usage V1 Organizations  Organization Id  Usage Get
          description: Successful Response
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Malformed request, header, cursor, or multipart form field.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Missing, malformed, unknown, revoked, or expired credential.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Authenticated principal lacks the required scope or role.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Resource not found, including cross-organization resources.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Idempotency conflict or invalid resource state.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Public error
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Rate limit exceeded.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
      security:
      - BearerAuth: []
      summary: Get Workspace Usage
      tags:
      - Usage
  /v1/usage/balance:
    get:
      description: 'Preflight the organization''s managed-AI funding before starting a run.


        Reports the organization''s billing state and execution-safe balance from

        the same wallet projection standard managed-run admission uses. Read-only

        and advisory — nothing is reserved by calling it, and the balance is

        model-agnostic: whether a specific model''s turn can fund depends on that

        model''s per-turn reservation bound.'
      operationId: get_managed_ai_balance_v1_usage_balance_get
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAiBalanceResponse'
          description: Successful Response
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Malformed request, header, cursor, or multipart form field.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Missing, malformed, unknown, revoked, or expired credential.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Authenticated principal lacks the required scope or role.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Resource not found, including cross-organization resources.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Idempotency conflict or invalid resource state.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Public error
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Rate limit exceeded.
          headers:
            X-Request-Id:
              description: Canonical everyn request ID generated by the API.
              schema:
                examples:
                - req_abc123
                type: string
      security:
      - BearerAuth: []
      summary: Get Managed Ai Balance
      tags:
      - Usage
components:
  schemas:
    WorkspaceManagedAiExpirationResponse:
      additionalProperties: false
      properties:
        amount:
          $ref: '#/components/schemas/CustomerMoneyResponse'
        expiresAt:
          format: date-time
          title: Expiresat
          type: string
      required:
      - expiresAt
      - amount
      title: WorkspaceManagedAiExpirationResponse
      type: object
    WorkspaceUsageResponse:
      additionalProperties: false
      properties:
        availability:
          const: available
          title: Availability
          type: string
        billingAccountId:
          title: Billingaccountid
          type: string
        calculatedAt:
          format: date-time
          title: Calculatedat
          type: string
        includedRows:
          $ref: '#/components/schemas/WorkspaceIncludedRowsResponse'
        managedAi:
          $ref: '#/components/schemas/WorkspaceManagedAiResponse'
        organizationId:
          title: Organizationid
          type: string
        payg:
          $ref: '#/components/schemas/WorkspacePaygResponse'
        period:
          $ref: '#/components/schemas/WorkspaceUsagePeriodResponse'
        primaryConsequence:
          enum:
          - subscription_hard_stop
          - financial_hold
          - row_risk_hold
          - managed_ai_unavailable
          - rows_unavailable
          - usage_low
          - available
          title: Primaryconsequence
          type: string
      required:
      - availability
      - organizationId
      - billingAccountId
      - calculatedAt
      - period
      - includedRows
      - payg
      - managedAi
      - primaryConsequence
      title: WorkspaceUsageResponse
      type: object
    WorkspaceUsageUnavailableResponse:
      additionalProperties: false
      properties:
        availability:
          const: unavailable
          title: Availability
          type: string
        billingAccountId:
          title: Billingaccountid
          type: string
        calculatedAt:
          format: date-time
          title: Calculatedat
          type: string
        managedAi:
          anyOf:
          - $ref: '#/components/schemas/WorkspaceManagedAiResponse'
          - type: 'null'
        organizationId:
          title: Organizationid
          type: string
        primaryConsequence:
          enum:
          - subscription_hard_stop
          - financial_hold
          - rows_unavailable
          title: Primaryconsequence
          type: string
        reason:
          const: row_period_unavailable
          title: Reason
          type: string
      required:
      - organizationId
      - billingAccountId
      - calculatedAt
      - availability
      - reason
      - managedAi
      - primaryConsequence
      title: WorkspaceUsageUnavailableResponse
      type: object
    PublicFieldError:
      additionalProperties: false
      properties:
        actual: {}
        code:
          type: string
        expected: {}
        message:
          type: string
        source:
          $ref: '#/components/schemas/PublicFieldErrorSource'
      required:
      - source
      - code
      - message
      type: object
    WorkspaceIncludedRowsResponse:
      additionalProperties: false
      properties:
        remaining:
          minimum: 0.0
          title: Remaining
          type: integer
        status:
          enum:
          - available
          - low
          - exhausted
          title: Status
          type: string
        total:
          minimum: 0.0
          title: Total
          type: integer
        used:
          minimum: 0.0
          title: Used
          type: integer
      required:
      - used
      - total
      - remaining
      - status
      title: WorkspaceIncludedRowsResponse
      type: object
    PublicError:
      additionalProperties: false
      properties:
        code:
          type: string
        details:
          additionalProperties: true
          type: object
        docsUrl:
          format: uri
          type: string
        fieldErrors:
          items:
            $ref: '#/components/schemas/PublicFieldError'
          type: array
        message:
          type: string
        requestId:
          type: string
        status:
          type: integer
      required:
      - status
      - code
      - message
      - requestId
      - docsUrl
      - fieldErrors
      type: object
    CustomerMoneyResponse:
      additionalProperties: false
      properties:
        amount:
          description: Exact base-10 amount serialized without binary floating point or exponent notation.
          examples:
          - '20.00'
          pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$
          title: Amount
          type: string
        currencyCode:
          maxLength: 3
          minLength: 3
          title: Currencycode
          type: string
      required:
      - currencyCode
      - amount
      title: CustomerMoneyResponse
      type: object
    WorkspaceUsagePeriodResponse:
      additionalProperties: false
      properties:
        end:
          format: date-time
          title: End
          type: string
        id:
          title: Id
          type: string
        start:
          format: date-time
          title: Start
          type: string
      required:
      - id
      - start
      - end
      title: WorkspaceUsagePeriodResponse
      type: object
    WorkspaceManagedAiSourceResponse:
      additionalProperties: false
      properties:
        available:
          $ref: '#/components/schemas/CustomerMoneyResponse'
        kind:
          enum:
          - cardless_sample
          - promotional
          - recurring
          - purchased
          - correction
          title: Kind
          type: string
      required:
      - kind
      - available
      title: WorkspaceManagedAiSourceResponse
      type: object
    WorkspacePaygResponse:
      additionalProperties: false
      properties:
        acceptedBudget:
          $ref: '#/components/schemas/CustomerMoneyResponse'
        committedBudget:
          $ref: '#/components/schemas/CustomerMoneyResponse'
        enabled:
          title: Enabled
          type: boolean
        ratedRows:
          minimum: 0.0
          title: Ratedrows
          type: integer
        remainingBudget:
          $ref: '#/components/schemas/CustomerMoneyResponse'
        status:
          enum:
          - 'off'
          - available
          - low
          - exhausted
          title: Status
          type: string
      required:
      - enabled
      - ratedRows
      - acceptedBudget
      - committedBudget
      - remainingBudget
      - status
      title: WorkspacePaygResponse
      type: object
    PublicErrorEnvelope:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/PublicError'
      required:
      - error
      type: object
    WorkspaceManagedAiResponse:
      additionalProperties: false
      properties:
        executionSafe:
          $ref: '#/components/schemas/CustomerMoneyResponse'
        nextExpiration:
          anyOf:
          - $ref: '#/components/schemas/WorkspaceManagedAiExpirationResponse'
          - type: 'null'
        settledBalance:
          $ref: '#/components/schemas/CustomerMoneyResponse'
        sources:
          items:
            $ref: '#/components/schemas/WorkspaceManagedAiSourceResponse'
          title: Sources
          type: array
        status:
          enum:
          - available
          - low
          - unavailable
          title: Status
          type: string
      required:
      - executionSafe
      - settledBalance
      - status
      - sources
      - nextExpiration
      title: WorkspaceManagedAiResponse
      type: object
    ManagedAiBalanceResponse:
      additionalProperties: false
      properties:
        calculatedAt:
          format: date-time
          title: Calculatedat
          type: string
        executionSafe:
          anyOf:
          - $ref: '#/components/schemas/CustomerMoneyResponse'
          - type: 'null'
          description: 'Execution-safe managed-AI balance at calculatedAt: the value runtime admission would fund new work against, net of open per-action holds. Advisory, not a reservation. Settlement drains the wallet asynchronously after rows complete, so recently finished work may not be reflected yet, and concurrent runs can still exhaust the wallet mid-run. Model-agnostic: admission reserves a per-turn bound that varies by model, so a small positive balance may still be denied as insufficient for a single turn of an expensive model. A run that outspends the wallet pauses with resumeAvailable rather than losing work, its unfunded rows failing as billing.wallet_admission_denied (agent-query runs pause with reason cached_balance_exhausted). Null when no balance can be stated — the organization has never been granted managed-AI value, or its ledger could not currently be read; spendingAllowed is false in both cases, while a drained wallet reads "0.00".'
        spendingAllowed:
          description: Whether the organization's billing state permits new paid work. False while a financial hold, an unpaid-invoice suspension, or missing paid-period authority stands against the account, regardless of remaining balance. Create, start, and resume refuse those same states; treat false as do-not-start-paid-work. A watcher already draining a running run may still send until its pause-cache snapshot re-reads zero.
          title: Spendingallowed
          type: boolean
        status:
          enum:
          - available
          - low
          - unavailable
          title: Status
          type: string
      required:
      - calculatedAt
      - spendingAllowed
      - executionSafe
      - status
      title: ManagedAiBalanceResponse
      type: object
    PublicFieldErrorSource:
      additionalProperties: false
      minProperties: 1
      properties:
        formField:
          type: string
        header:
          type: string
        parameter:
          type: string
        pointer:
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http
    BrowserCsrf:
      description: csrfToken returned by GET /v1/auth/session for the same authenticated browser session.
      in: header
      name: X-CSRF-Token
      type: apiKey
    BrowserSession:
      description: HttpOnly session cookie issued by browser login; deployment may configure its name.
      in: cookie
      name: everyn_session
      type: apiKey