openapi: 3.0.3
info:
  title: naturali.ai — Users API
  version: 1.0.0
  description: >
    The account behind a credential. The Auth API mints and rotates credentials;
    this one reads and edits the user they resolve to, whether that credential is
    an app session JWT or a naturali API key (nat_sk_…).

    `/me` is the only subject this module addresses: nothing in the product gives
    one tenant the right to read another's account, so there is no
    `GET /v1/users/{user_id}` and no directory a tenant can reach. A colleague's
    email surfaces only through the membership listing of a project you are
    already in (`GET /v1/projects/{project_id}/members`).

    Reading or changing *another* account needs the `admin` platform role and an
    operator route, which this contract does not describe.

    The email address is deliberately not editable here. It *is* the credential —
    a code sent to it is how an account is created and signed into — so changing
    it is an authentication flow that must prove control of the new address, not
    a profile edit.
  contact:
    name: naturali.ai
    url: https://naturali.ai
servers:
  - url: '{baseUrl}'
    description: Host of your naturali.ai deployment; every path carries the /v1 prefix.
    variables:
      baseUrl:
        description: Base host URL.
        default: https://api.naturali.ai
tags:
  - name: Users
    description: Read and edit the authenticated account.
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/users/me:
    get:
      tags: [Users]
      summary: Get the current user
      description: Returns the account the presented credential resolves to.
      operationId: getCurrentUser
      responses:
        '200':
          description: The authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      tags: [Users]
      summary: Update the current user
      description: >
        Edits the account's display name and whether it receives usage alerts.
        At least one field is required, so a request that misspelled a field is
        rejected rather than answered with a silent 200. Send `name: null` to
        clear the name.


        With `usage_alerts` on, the account is emailed once each time its model
        credit, its runs this month or its indexed storage reaches 75%, 90% and
        100%. Credit is measured as the share spent this month of what the month
        had available, so a top-up lowers it. Usage falling back below a level
        re-arms that level. Figures are read every 15 minutes, so an alert can
        arrive up to that long after the crossing.
      operationId: updateCurrentUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: The updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
  /v1/users/me/billing:
    get:
      tags: [Users]
      summary: Get the current account's billing standing
      description: >
        The plan the account is on, how long its projects may keep content, how
        much indexed storage it is holding, and the credit it has left — the
        figures the platform already enforces against, readable by the account
        they are enforced against.


        A managed-model generation is refused with `402 INSUFFICIENT_CREDIT`
        while `credit_balance_usd` is negative, and a feature or a resource count
        outside the plan is refused with `403`, as is a retention window wider
        than `retention_days` or an ingest past `storage.limit`. Every refusal
        names what is missing; this is where the numbers behind them are read.


        Every figure here is a local read, which is what keeps this route cheap
        enough to poll — unlike `GET /v1/users/me/usage`, which asks the meter
        once per project.


        Answers for the caller's own account only, and always the account the
        credential resolves to — an API key answers for the user that minted it.
        The plan gating a *project* is that project's billing owner's, so a
        member of someone else's project reads their own rung here, not that
        project's.
      operationId: getCurrentUserBilling
      responses:
        '200':
          description: The account's plan and credit standing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBilling'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
  /v1/users/me/usage:
    get:
      tags: [Users]
      summary: Get the current account's usage this billing cycle
      description: >
        What the account uses this billing cycle, per project and against its
        plan: runs, indexed storage, and the counts the plan caps — projects,
        active channels and triggers.


        How many runs the account has made this billing cycle, and how many its
        plan includes. A **run is one agent generation or one tool call** — the
        unit every rung is priced in. Every tool call counts, including those an
        agent makes inside a generation; a `client` tool counts nothing.


        Counted across the projects this account is the billing owner of, over
        the current UTC calendar month, from the meter itself. Archived projects
        are included: the runs they already made were made.


        **On the `free` plan the allowance is enforced.** An account that has
        used it is refused `403 PLAN_LIMIT_REACHED` with `resource: "runs"` on
        everything that starts a generation and on a direct tool call — on its
        own provider credential as
        much as on a managed model, because a run is a run — until the billing
        month turns or it upgrades. On `pro` and `business` nothing is refused:
        runs past the allowance are billed at the overage rate those plans are
        sold with. A contract plan is not counted.


        The other thing that stops a managed-model generation is a negative
        credit balance, which is `GET /v1/users/me/billing`, and it never
        applies to your own credential.


        **This route counts live; the refusal reads a figure counted every few
        minutes.** So the two can differ by a burst: this is the more current
        number, and a refusal quotes the one it actually enforced.


        It is also more expensive than the balance read: it reads the runtime
        several times per project. Poll it on the order of minutes, not seconds.
        A figure that could not be read is `null` rather than failing the
        request.
      operationId: getCurrentUserUsage
      responses:
        '200':
          description: The account's usage for the cycle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserUsage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
  /v1/users/me/credits:
    get:
      tags: [Users]
      summary: List the current account's credit ledger
      description: >
        A cursor page of the account's model-credit ledger, newest first, with
        the balance the whole ledger sums to. The ledger is append-only: a
        correction is a new line, never an edit.


        A `usage` line is managed model spend, written as the meter is
        reconciled every 15 minutes per project, so the ledger grows by a line
        per project per window that spent anything. Filter with `kind`.
      operationId: listCurrentUserCredits
      parameters:
        - name: kind
          in: query
          required: false
          description: Only lines of this kind.
          schema:
            type: string
            enum: [included, purchased, granted, usage]
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of the ledger.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AccountCreditEntry'
                      credit_balance_usd:
                        type: number
                        description:
                          The sum of the whole ledger, not only of this page. Spend is included as
                          it is reconciled, so read it with `spend_reconciled_at`.
                        example: 8.98
                      spend_reconciled_at:
                        type: string
                        format: date-time
                        nullable: true
                        description:
                          When this account's managed spend was last compared against the meter —
                          the oldest such moment across its projects. Null when at least one project has never
                          been reconciled.
                        example: '2026-07-14T12:15:00.000Z'
                    required:
                      - credit_balance_usd
                      - spend_reconciled_at
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
  /v1/users/me/stops:
    get:
      tags: [Users]
      summary: List what a billing ceiling stopped
      description: >
        Schedule triggers, eval runs, orchestration runs and workflow tasks the
        platform stopped on this account's projects because the credit balance
        went below zero or a Free plan's runs ran out, and that have not been
        restored or dismissed yet. Newest first.


        `blocked_by` names the ceiling still closed: while it is set, nothing
        can be restored. Top up for `debt`; upgrade or wait for the month to turn
        for `run_allowance`.
        A project-confined key sees its own project's stops only.
      operationId: listCurrentUserStops
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of stops still listed.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/SpendStop'
                      blocked_by:
                        type: string
                        enum:
                          - debt
                          - run_allowance
                        nullable: true
                        description: The ceiling still closed, which blocks every restore; null when none is.
                    required:
                      - blocked_by
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/users/me/stops/{stop_id}/restore:
    post:
      tags: [Users]
      summary: Restore a stopped item
      description: >
        Turns one stopped item back on — re-enables the schedule trigger, or
        resumes the orchestration run or workflow task — and stops listing it.
        An item that is no longer stopped (resumed already, finished or deleted)
        is marked restored too.


        Refused with `409 STOP_CEILING_CLOSED` while a ceiling is still closed,
        naming it in `meta.blocked_by`, and with `409 STOP_NOT_RESTORABLE` for
        a cancelled eval run, which can only be dismissed.
      operationId: restoreCurrentUserStop
      parameters:
        - $ref: '#/components/parameters/stop_id'
      responses:
        '200':
          description: The restored stop.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendStop'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/StopNotFound'
        '409':
          $ref: '#/components/responses/StopNotRestorable'
        '502':
          $ref: '#/components/responses/StopRestoreUnavailable'
  /v1/users/me/stops/{stop_id}:
    delete:
      tags: [Users]
      summary: Dismiss a stopped item
      description: >
        Stops listing an item without turning it back on. Allowed while a
        ceiling is still closed.
      operationId: dismissCurrentUserStop
      parameters:
        - $ref: '#/components/parameters/stop_id'
      responses:
        '204':
          description: Dismissed.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/StopNotFound'
  /v1/users/me/statements:
    get:
      tags: [Users]
      summary: List the account's monthly statements
      description: >
        What the account owes for each closed billing month, newest first: the
        subscription fee, prorated by the share of the month each plan was held,
        and runs past the allowance at the plan's overage rate, less what was
        paid at an upgrade. Overage is measured against the highest plan held
        that month.


        A statement is written within an hour of the month closing, once, and
        never changes; `payment_status` follows its charge on the saved card.
        It is not a tax invoice. Months on the Free plan alone, contract plans
        and storage are not stated.
      operationId: listCurrentUserStatements
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of statements.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Statement'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
  /v1/users/me/statements/{statement_id}:
    get:
      tags: [Users]
      summary: Get a monthly statement
      description: >
        One of this account's monthly statements, with its lines and total.
        Another account's statement answers `404`.
      operationId: getCurrentUserStatement
      parameters:
        - name: statement_id
          in: path
          required: true
          description: The statement's ID (stm_ prefix).
          schema:
            type: string
      responses:
        '200':
          description: The statement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Statement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
        '404':
          description: No such statement on this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/users/me/top-ups:
    post:
      tags: [Users]
      summary: Top up credit
      description: >
        Buys model credit for the caller's account. Once the card is charged the
        full amount is added to `credit_balance_usd` as purchased credit, which
        never expires. The card fee is not deducted. `amount_usd` is what is
        credited; a card issued in Brazil is charged its equivalent in
        Brazilian reais at the Banco Central's latest closing PTAX selling
        rate, and a checkout shows reais to a payer in Brazil.


        With `saved_card: true` the saved card is charged at once and the
        answer is `status: paid`. When the card needs authentication or is
        declined, nothing is charged and the answer falls back to a checkout.


        A checkout (`status: checkout`) is a hosted page: send the caller to
        `checkout_url`. Creating it charges nothing, and one left unpaid lapses
        at `expires_at`. The card paid with there becomes the account's saved
        card, replacing any other. After paying, the browser returns to the
        app's billing page.
      operationId: createCurrentUserTopUp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopUpCreate'
      responses:
        '201':
          description: The paid top-up, or the checkout to send the caller to.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUp'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BillingForbidden'
        '409':
          description: '`saved_card` with no saved card (`PAYMENT_METHOD_REQUIRED`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: >-
            The payment provider could not be reached
            (`PAYMENT_PROVIDER_ERROR`). Nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Card payments are not available on this deployment
            (`PAYMENTS_NOT_CONFIGURED`), or the exchange rate for a card
            charged in reais could not be read (`EXCHANGE_RATE_UNAVAILABLE`).
            Nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/users/me/payment-method:
    get:
      tags: [Users]
      summary: Get the saved card
      description: >
        The card auto-recharge and monthly statements are charged to, as the
        payment provider reports it. Only the brand, last four digits, expiry
        and issuing country are kept here. A card issued in Brazil is charged
        in Brazilian reais, every other card in US dollars.
      operationId: getCurrentUserPaymentMethod
      responses:
        '200':
          description: The saved card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
        '404':
          description: The account has no saved card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags: [Users]
      summary: Start saving a card
      description: >
        A hosted page that saves a card for charges made without the payer
        present: auto-recharge and monthly statements. Send the caller to
        `checkout_url`; nothing is charged. A card saved this way replaces the
        one already saved.
      operationId: createCurrentUserPaymentMethod
      responses:
        '201':
          description: The page to send the caller to.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodSetup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BillingForbidden'
        '502':
          description: The payment provider could not be reached (`PAYMENT_PROVIDER_ERROR`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Card payments are not available on this deployment (`PAYMENTS_NOT_CONFIGURED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Users]
      summary: Remove the saved card
      description: >
        Forgets the saved card and turns auto-recharge off. Refused while a
        paid plan is in effect or is the next plan, or a statement is not yet
        settled: move to Free first, and remove the card once Free is in
        effect and its last statement is paid.
      operationId: deleteCurrentUserPaymentMethod
      responses:
        '204':
          description: The card is removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BillingForbidden'
        '404':
          description: The account has no saved card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >
            A paid plan is in effect or next, or a statement is unsettled
            (`PAID_PLAN_REQUIRES_CARD`); `meta` carries `plan`, `next_plan`
            and `unpaid_statement`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Card payments are not available on this deployment (`PAYMENTS_NOT_CONFIGURED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/users/me/auto-recharge:
    get:
      tags: [Users]
      summary: Get the auto-recharge setting
      description: >
        Whether the credit balance is topped up on the saved card, by how much
        and below what balance. `enabled` is false until a card is saved and
        the setting turned on.
      operationId: getCurrentUserAutoRecharge
      responses:
        '200':
          description: The setting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoRecharge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
    put:
      tags: [Users]
      summary: Turn auto-recharge on
      description: >
        Top up `amount_usd` on the saved card whenever the credit balance falls
        below `below_usd`. Checked every 15 minutes, at most one charge an
        hour. A declined charge turns it off and emails the account.
      operationId: setCurrentUserAutoRecharge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoRechargeUpdate'
      responses:
        '200':
          description: The setting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoRecharge'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BillingForbidden'
        '409':
          description: The account has no saved card (`PAYMENT_METHOD_REQUIRED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Users]
      summary: Turn auto-recharge off
      description: >
        Stops topping up the balance automatically. The saved card stays saved.
      operationId: disableCurrentUserAutoRecharge
      responses:
        '200':
          description: The setting, now off.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoRecharge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BillingForbidden'
  /v1/users/me/plan:
    put:
      tags: [Users]
      summary: Change the plan
      description: >
        Choose `free`, `pro` or `business`.


        An upgrade is charged for the price difference over the rest of the
        month, then takes effect; the month's statement nets that payment out.
        The saved card is charged at once, in its currency. With no saved card,
        or when the card needs authentication or is declined, nothing is
        charged and the answer carries a `checkout_url`: a hosted page that
        charges the upgrade and saves the card. The plan changes once it is
        paid; one left unpaid lapses at `expires_at`.


        A downgrade takes effect when the month ends, and `next_plan` names it
        until then. A contract plan is changed by asking us.
      operationId: setCurrentUserPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPlanChangeRequest'
      responses:
        '200':
          description: The plan in effect and the one coming.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPlanChange'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BillingForbidden'
        '409':
          description: >-
            A paid plan with nothing to charge now and no saved card for its
            statement (`PAYMENT_METHOD_REQUIRED`), or a contract plan
            (`PLAN_BY_CONTRACT`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: The payment provider could not be reached (`PAYMENT_PROVIDER_ERROR`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Card payments are not available on this deployment
            (`PAYMENTS_NOT_CONFIGURED`), or the exchange rate for a card
            charged in reais could not be read (`EXCHANGE_RATE_UNAVAILABLE`);
            the plan is unchanged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/users/me/plan/quote:
    get:
      tags: [Users]
      summary: Preview a plan change
      description: >
        What choosing `plan` would charge now: an upgrade's share of the rest
        of the month, else 0. Changes nothing.
      operationId: getCurrentUserPlanQuote
      parameters:
        - name: plan
          in: query
          required: true
          schema:
            type: string
            enum: [free, pro, business]
      responses:
        '200':
          description: The charge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPlanQuote'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountWideOnly'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A naturali API key (nat_sk_…) or a session JWT.
    oauth2:
      type: oauth2
      description: >-
        A connected app's OAuth access token, issued by this API's authorization
        server (discovery: /.well-known/oauth-authorization-server). Its one scope
        carries every operation, confined to the projects the user chose when
        approving the app.
      flows:
        authorizationCode:
          authorizationUrl: https://api.naturali.ai/authorize
          tokenUrl: https://api.naturali.ai/token
          refreshUrl: https://api.naturali.ai/token
          scopes:
            mcp:access: Every operation this API serves, on the projects the grant covers.
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: >-
        Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1
        or not an integer it is `400`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: >-
        The previous page's `next_cursor`; omit it for the first page. A cursor
        this list did not issue is `400`.
      schema:
        type: string
    stop_id:
      name: stop_id
      in: path
      required: true
      description: The stop's ID (sst_ prefix).
      schema:
        type: string
  responses:
    StopNotFound:
      description: No such stop on this account, or it was already restored or dismissed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    StopNotRestorable:
      description: The stop cannot be restored now.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    StopRestoreUnavailable:
      description: The runtime could not turn the item back on; the stop stays listed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    AccountWideOnly:
      description: >-
        `FORBIDDEN`: the credential is confined to one project. Account
        routes need an account-wide credential.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BillingForbidden:
      description: >-
        `FORBIDDEN`: the credential is confined to one project, or is a
        connected app's. Billing changes need an account-wide key or a
        signed-in user.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Page:
      type: object
      description:
        One page of a list. Rows inserted or removed between two calls neither repeat nor skip
        a row on the next page.
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          description: This page's items, in the list's order.
          items: {}
        next_cursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page; `null` on the last page.
    User:
      type: object
      properties:
        id:
          type: string
          description: Public user ID (user_ prefix).
          example: user_V1StGXR8Z5jdHi6B
        email:
          type: string
          description: "The address sign-in codes are sent to. Read-only here."
          format: email
          example: ana@acme.com
        name:
          type: string
          description: "Display name."
          nullable: true
          example: Ana Silva
        email_verified:
          type: boolean
          description: "Whether the address has completed a sign-in code exchange."
          example: true
        roles:
          type: array
          description: >-
            Roles on naturali itself, not on a project. Empty for almost every
            account; `admin` marks a naturali operator. Changed only through
            `PUT /v1/admin/users/{user_id}/roles`, by a caller holding the role
            that grants each one.
          items:
            type: string
            enum: [admin]
          example: []
        usage_alerts:
          type: boolean
          description: >-
            Whether the account is emailed when its model credit, runs or
            indexed storage reaches 75%, 90% and 100%. On for a new account.
          example: true
        created_at:
          type: string
          format: date-time
          example: '2026-07-17T00:00:00.000Z'
      required: [id, email, email_verified, roles, usage_alerts, created_at]
    UserUpdate:
      type: object
      minProperties: 1
      description: Send at least one field.
      properties:
        name:
          type: string
          nullable: true
          description: Display name; null clears it.
          example: Ana Silva
        usage_alerts:
          type: boolean
          description: >-
            Email the account at 75%, 90% and 100% of its model credit, runs
            and indexed storage.
          example: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: >-
            Structured error. Every error response uses this shape, so `code` can
            be read without first checking the type of `error`.
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              pattern: '^[A-Z][A-Z0-9_]*$'
              description: >-
                Machine-readable error code, UPPER_SNAKE whether naturali or the
                runtime raises it.
              example: FORBIDDEN
            message:
              type: string
              description: Human-readable explanation.
              example: Your role in this project does not carry this action.
            hint:
              type: string
              description: >-
                What to do about it, naming the routes of this API to call. For
                people and agents; it may change, so branch on `code`.
              example: >-
                Use a credential whose scope includes this action, or ask a
                project `admin` or `owner` to act; the caller's role or key
                excludes it.
            meta:
              type: object
              additionalProperties: true
              description: >-
                Structured context, such as the `resource` and `limit` of a
                `PLAN_LIMIT_REACHED`.
    UserBilling:
      type: object
      required:
        [
          plan,
          next_plan,
          retention_days,
          credit_balance_usd,
          spend_reconciled_at,
          storage,
        ]
      properties:
        plan:
          type: string
          description: >-
            The rung of the infra subscription in effect for this account: the
            highest it held this month. `free` for an account with no
            subscription, which is also the least-privileged rung. It gates the
            feature lines and the resource counts of the pricing table.
          enum: [free, pro, business, enterprise]
        next_plan:
          type: string
          description: >-
            The rung the account moves to when the month turns. It differs from
            `plan` only while a downgrade is pending: a downgrade takes effect
            at the end of the month, an upgrade at once.
          enum: [free, pro, business, enterprise]
          example: pro
        retention_days:
          type: integer
          nullable: true
          description: >-
            The longest window a project of this account may keep trace and
            generation content for, in days. A `PATCH` asking for a wider one —
            `null` included, which keeps content indefinitely — is refused with
            `403 PLAN_LIMIT_REACHED`; anything shorter is always allowed. On a
            plan whose window a contract sets, this is that contract's figure,
            and `null` means nothing bounds it. A plan change that shortens the
            window applies at the end of the billing cycle, so this reads as the
            widest window held during the current one.
          example: 30
        credit_balance_usd:
          type: number
          description: >-
            Model credit left, in US dollars — granted and purchased credit plus
            the plan's monthly allowance, less managed-model and embedding
            spend. Managed generations and writes that embed are refused while
            this is negative; zero is not. Only as current as
            `spend_reconciled_at`, so read the two together.
          example: 18.42
        spend_reconciled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When spend was last read off the meter and written to the ledger.
            `null` when it has never been read for at least one of the account's
            projects, or the account has none — a balance whose spend has never
            been read is not current as of anything.
          example: '2026-07-17T00:15:00.000Z'
        storage:
          type: object
          description: >-
            The account's indexed-storage pool, in the metered gigabytes the
            ceiling is enforced in — the raw file plus every chunk's text and
            its embedding vector, so not the size of what you uploaded. Pooled
            across every project the account pays for; per project, read the
            `gb_day` component of `GET /v1/projects/{project_id}/usage`. An
            ingest past `limit` is refused with `403 PLAN_LIMIT_REACHED`,
            `resource: "storage"`, whose `meta` carries the same `limit` and
            `used`.
          required: [used, limit, sampled_at]
          properties:
            used:
              type: number
              description: GB held across the account's projects.
              example: 12.4137
            limit:
              type: number
              nullable: true
              description: >-
                GB the plan allows; null where a contract sets the ceiling, or
                where the plan sets none.
              example: 30
            sampled_at:
              type: string
              format: date-time
              nullable: true
              description: >-
                When the **oldest** sample behind `used` was taken — the total
                is only as current as its stalest part, measured every few
                minutes per project rather than on this request. Null when a
                project has never been sampled, or there are none.
              example: '2026-07-17T00:15:00.000Z'
    UserUsage:
      type: object
      required:
        [cycle_from, pending_spend_usd, spendable_balance_usd, projects, limits]
      properties:
        cycle_from:
          type: string
          format: date-time
          description: >-
            Start of the billing cycle the runs were counted over — the first
            instant of the current UTC calendar month.
          example: '2026-07-01T00:00:00.000Z'
        pending_spend_usd:
          type: number
          nullable: true
          description: >-
            Model and embedding spend metered since the balance was last
            reconciled, across every project the account pays for. `null` when
            at least one project's meter could not be read.
          example: 1.43
        spendable_balance_usd:
          type: number
          nullable: true
          description: >-
            The credit balance less `pending_spend_usd`. A managed generation
            can be refused with `402 INSUFFICIENT_CREDIT` while the credit
            balance still reads positive; while this is zero or above, none is.
            Check it before starting work that runs several generations. `null`
            when `pending_spend_usd` is.
          example: 23.35
        projects:
          type: array
          description: >-
            Every project the account pays for, oldest first, archived ones
            included. Empty for an account with no projects.
          items:
            $ref: '#/components/schemas/AccountProjectUsage'
        limits:
          $ref: '#/components/schemas/UsageLimits'
    AccountProjectUsage:
      type: object
      required:
        [
          project_id,
          name,
          status,
          runs,
          triggers,
          channels,
          storage,
          pending_spend_usd,
        ]
      properties:
        project_id:
          type: string
          x-naturali-ref: projects
          example: proj_V1StGXR8Z5jdHi6B
        name:
          type: string
          nullable: true
          description: The project's name; `null` when it could not be read.
          example: Support
        status:
          type: string
          enum: [active, archived]
          example: active
        runs:
          type: integer
          nullable: true
          description: Runs this cycle; `null` when this project's meter could not be read.
          example: 1284
        triggers:
          type: integer
          nullable: true
          description: Triggers the project holds; `null` when they could not be counted.
          example: 2
        channels:
          type: integer
          description: >-
            Channels in the `active` state, the ones the `channels` limit
            counts. A `disabled` one does not count.
          example: 1
        storage:
          type: object
          required: [used, sampled_at]
          properties:
            used:
              type: number
              nullable: true
              description: >-
                GB of indexed storage as of the last sample; `null` when the
                project has never been sampled.
              example: 0.42
            sampled_at:
              type: string
              format: date-time
              nullable: true
              description: When `used` was sampled.
              example: '2026-07-14T12:00:00.000Z'
        pending_spend_usd:
          type: number
          nullable: true
          description: >-
            This project's spend metered since the balance was last reconciled;
            `null` when its meter could not be read.
          example: 1.43
    UsageLimits:
      type: object
      description: >-
        Each plan-limited resource, counted across every project the account
        pays for, beside the rung's ceiling — keyed by the `resource` a
        `403 PLAN_LIMIT_REACHED` names, whose `meta` carries the same `used`
        and `limit`.
      required: [projects, channels, triggers, storage, runs]
      properties:
        projects:
          $ref: '#/components/schemas/UsageLimit'
        channels:
          $ref: '#/components/schemas/UsageLimit'
        triggers:
          $ref: '#/components/schemas/UsageLimit'
        storage:
          $ref: '#/components/schemas/UsageLimit'
        runs:
          description: >-
            Runs this cycle against the plan's allowance. `used` is `null` when
            a project's meter could not be read — a total missing a project
            would claim headroom that may not exist — and `limit` is `null` on a
            contract plan. Past it, `free` is refused and `pro` and `business`
            are billed overage.
          allOf:
            - $ref: '#/components/schemas/UsageLimit'
    UsageLimit:
      type: object
      required: [used, limit]
      properties:
        used:
          type: number
          nullable: true
          description: >-
            How much is held; `null` when a project's part of it could not be
            read.
          example: 2
        limit:
          type: number
          nullable: true
          description: The rung's ceiling; `null` when it sets none.
          example: 3
    AccountCreditEntry:
      type: object
      required: [id, kind, amount_usd, reason, project_id, created_at]
      properties:
        id:
          type: string
          description: Public ledger-line ID (cre_ prefix).
          example: cre_V1StGXR8Z5jdHi6B
        kind:
          type: string
          description: >-
            Where the credit came from. `included` is a plan's monthly allowance
            and does not carry past the cycle; `purchased` is a top-up and never
            expires; `granted` is credit naturali gave. `usage` is managed model
            spend, debited from the meter.
          enum: [included, purchased, granted, usage]
          example: usage
        amount_usd:
          type: number
          description: US dollars, signed. Negative lines are spend or corrections.
          example: -0.42
        reason:
          type: string
          nullable: true
          description: What the line is for.
          example: Model usage, 2026-07.
        project_id:
          type: string
          nullable: true
          description: >-
            This account's project the line belongs to: the one whose meter
            produced a `usage` line.
            Null for a line to the account itself.
          example: proj_V1StGXR8Z5jdHi6B
        created_at:
          type: string
          format: date-time
          example: '2026-07-14T12:15:00.000Z'
    SpendStop:
      type: object
      required:
        [
          id,
          project_id,
          kind,
          resource_id,
          reason,
          restorable,
          stopped_at,
          resolution,
          resolved_at,
        ]
      properties:
        id:
          type: string
          example: sst_V1StGXR8Z5jdHi6B
        project_id:
          type: string
          example: proj_V1StGXR8Z5jdHi6B
        kind:
          type: string
          enum:
            [
              schedule_trigger,
              eval_run,
              orchestration_run,
              workflow_task,
              playbook_case,
            ]
          description: >-
            What was stopped: a schedule trigger is disabled, an eval run
            cancelled, an orchestration run, a workflow task's automation or a
            playbook case's cascade paused.
        resource_id:
          type: string
          description: The stopped trigger, eval run, orchestration run, task or playbook case.
          example: trg_V1StGXR8Z5jdHi6B
        reason:
          type: string
          enum: [debt, run_allowance]
          description: >-
            The ceiling that stopped it: a credit balance below zero, or a Free
            plan's runs for the month used up.
        restorable:
          type: boolean
          description: False for a cancelled eval run, which can only be dismissed.
        stopped_at:
          type: string
          format: date-time
        resolution:
          type: string
          enum: [restored, dismissed]
          nullable: true
        resolved_at:
          type: string
          format: date-time
          nullable: true
    StatementLine:
      type: object
      required:
        [
          kind,
          plan,
          description,
          period_from,
          period_to,
          quantity,
          unit,
          unit_price_usd,
          amount_usd,
        ]
      properties:
        kind:
          type: string
          enum:
            [
              subscription,
              run_overage,
              prepaid,
              model_credit_spend,
            ]
          description: >-
            `subscription`, `run_overage` and `prepaid` make up `total_usd`
            and are charged; `prepaid` is fee already paid by card at an
            upgrade, netted as a negative amount. `model_credit_spend` reports
            the model credit spent in the cycle and is not part of it.
        plan:
          type: string
          enum: [free, pro, business, enterprise]
        description:
          type: string
          example: Pro plan, 2026-10-01 to 2026-10-31
        period_from:
          type: string
          format: date-time
        period_to:
          type: string
          format: date-time
          description: Exclusive.
        quantity:
          type: number
          description: >-
            For `subscription`, the share of the month the plan was held; for
            `run_overage`, the runs past the allowance; for `prepaid`, 1.
          example: 1
        unit:
          type: string
          enum: [month, '1,000 runs', payment, USD]
        unit_price_usd:
          type: number
          example: 49
        amount_usd:
          type: number
          example: 49
    Statement:
      type: object
      required:
        [
          id,
          cycle,
          period_from,
          period_to,
          runs,
          lines,
          total_usd,
          payment_status,
          created_at,
        ]
      properties:
        id:
          type: string
          example: stm_V1StGXR8Z5jdHi6B
        cycle:
          type: string
          description: The billing month, `YYYY-MM` in UTC.
          example: '2026-10'
        period_from:
          type: string
          format: date-time
        period_to:
          type: string
          format: date-time
          description: Exclusive.
        runs:
          type: object
          description: >-
            Runs that month across every project the account pays for, against
            the allowance overage was measured against.
          required: [used, limit]
          properties:
            used:
              type: integer
              example: 30000
            limit:
              type: integer
              nullable: true
              example: 25000
        lines:
          type: array
          items:
            $ref: '#/components/schemas/StatementLine'
        total_usd:
          type: number
          description: What is owed, after anything prepaid.
          example: 59
        payment_status:
          type: string
          enum: [unpaid, processing, paid, failed, nothing_due]
          description: >-
            Collection on the saved card. `unpaid` until a charge starts —
            within an hour of the statement, once a card is saved. `failed`
            moves the account to Free when the month ends.
        created_at:
          type: string
          format: date-time
    TopUpCreate:
      type: object
      required: [amount_usd]
      properties:
        amount_usd:
          type: number
          minimum: 5
          maximum: 999999.99
          description: US dollars to buy, in whole cents.
          example: 50
        saved_card:
          type: boolean
          default: false
          description: Charge the saved card now instead of opening a checkout.
    TopUp:
      type: object
      required: [id, amount_usd, status, checkout_url, expires_at]
      properties:
        id:
          type: string
          description: The payment's or the checkout's ID at the payment provider.
          example: cs_test_a1b2c3
        amount_usd:
          type: number
          description: >-
            What is credited once paid: charged in US dollars, or its
            equivalent in reais.
          example: 50
        status:
          type: string
          enum: [paid, checkout]
          description: >-
            `paid`: the saved card was charged and the credit added.
            `checkout`: nothing is charged until the caller pays at
            `checkout_url`.
        checkout_url:
          type: string
          format: uri
          nullable: true
          description: The hosted page that takes the card; `null` when paid.
          example: https://checkout.stripe.com/c/pay/cs_test_a1b2c3
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: When an unpaid checkout lapses; `null` when paid.
    PaymentMethod:
      type: object
      required: [brand, last4, exp_month, exp_year, currency, exchange_rate]
      properties:
        brand:
          type: string
          description: "Card brand, such as `visa`."
          example: visa
        last4:
          type: string
          description: "Last four digits."
          example: '4242'
        exp_month:
          type: integer
          description: "Expiry month."
          example: 12
        exp_year:
          type: integer
          description: "Expiry year."
          example: 2030
        currency:
          type: string
          enum: [usd, brl]
          description: What the card is charged in, from its issuing country.
          example: usd
        exchange_rate:
          type: number
          nullable: true
          description: >-
            Units of `currency` per US dollar for a charge made now: 1 for
            `usd`, the Banco Central's latest closing PTAX selling rate for
            `brl`. `null` while that rate cannot be read.
          example: 1
    PaymentMethodSetup:
      type: object
      required: [id, checkout_url, expires_at]
      properties:
        id:
          type: string
          description: The setup page's ID at the payment provider.
          example: cs_test_a1b2c3
        checkout_url:
          type: string
          format: uri
          description: The hosted page that takes the card.
          example: https://checkout.stripe.com/c/pay/cs_test_a1b2c3
        expires_at:
          type: string
          format: date-time
          description: When an unused page lapses.
    AutoRecharge:
      type: object
      required: [enabled, amount_usd, below_usd, last_attempted_at]
      properties:
        enabled:
          type: boolean
          description: "Whether the balance is topped up automatically."
        amount_usd:
          type: number
          nullable: true
          description: What each recharge buys. `null` while off.
          example: 20
        below_usd:
          type: number
          nullable: true
          description: The balance under which a recharge is charged. `null` while off.
          example: 5
        last_attempted_at:
          type: string
          format: date-time
          nullable: true
          description: When a recharge was last charged, whatever its outcome.
    AutoRechargeUpdate:
      type: object
      required: [amount_usd, below_usd]
      properties:
        amount_usd:
          type: number
          minimum: 5
          maximum: 999999.99
          description: US dollars per recharge, in whole cents.
          example: 20
        below_usd:
          type: number
          minimum: 0
          maximum: 999999.99
          description: Recharge when the balance falls below this, in whole cents.
          example: 5
    UserPlanChangeRequest:
      type: object
      required: [plan]
      properties:
        plan:
          type: string
          enum: [free, pro, business]
    UserPlanQuote:
      type: object
      required: [plan, charge_usd]
      properties:
        plan:
          type: string
          enum: [free, pro, business]
        charge_usd:
          type: number
          description: >-
            What `PUT /v1/users/me/plan` would charge now, before any
            conversion to reais; 0 when nothing.
          example: 24.5
    UserPlanChange:
      type: object
      required: [plan, next_plan, charged_usd, checkout_url, expires_at]
      properties:
        plan:
          type: string
          enum: [free, pro, business, enterprise]
          description: The plan in effect.
        next_plan:
          type: string
          enum: [free, pro, business, enterprise]
          description: The plan from next month.
        charged_usd:
          type: number
          description: What the saved card was charged now; 0 when nothing was.
          example: 24.5
        checkout_url:
          type: string
          format: uri
          nullable: true
          description: >-
            The hosted page the upgrade waits on, which charges it and saves
            the card; `null` when nothing waits.
          example: null
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: When an unpaid `checkout_url` lapses.
          example: null
