Daystruct Account API

openapi: 3.2.0
info:
  title: Daystruct Account API
  version: 1.0.0
  description: Discover reusable source, data and memory capabilities, inspect public release evidence and compatibility, and acquire or invoke through scoped endpoints. Public discovery is anonymous; acquisition, protected contents and paid operations require their documented scopes and credits. Source runs in the caller environment. Registering an agent declares identity; registration alone does not start a worker or make it routable. The evidence refinery is paused; legacy observations are no longer refreshed. Resolved values are best-supported current interpretations, not guarantees of complete or absolute truth.
servers:
- url: https://api.daystruct.ai
security:
- {}
- apiKey: []
tags:
- name: Account
paths:
  /api/v1/account:
    get:
      tags:
      - Account
      summary: 'The presented key''s account: credits, scopes and per-call spending limit'
      description: Read-only; needs a key with the read scope and never returns the key. Check credits.available before a paid call, show the user the price first, and tell them what was spent afterwards. key.maxRequestPriceCredits null means the key has no per-call limit; each call's own maxPriceCredits still applies. Also available as the MCP tool get_daystruct_account. Charged responses report creditsRemaining. A low balance returns 402 insufficient_credits with requiredCredits, availableCredits and topUpUrl; a price above a limit returns 402 price_exceeds_limit with limitedBy (request or api_key).
      security:
      - apiKey: []
      responses:
        '200':
          description: Account view
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                    - accountId
                    - credits
                    - key
                    - canSpend
                    - topUpUrl
                    properties:
                      accountId:
                        type: string
                      credits:
                        type: object
                        properties:
                          available:
                            type: integer
                          reserved:
                            type: integer
                          unit:
                            const: credits
                      key:
                        type: object
                        properties:
                          id:
                            type: string
                          label:
                            type: string
                          displayPrefix:
                            type: string
                          scopes:
                            type: array
                            items:
                              type: string
                          maxRequestPriceCredits:
                            type:
                            - integer
                            - 'null'
                          expiresAt:
                            type:
                            - string
                            - 'null'
                      canSpend:
                        type: boolean
                      topUpUrl:
                        type: string
                      keysUrl:
                        type: string
                      guidance:
                        type: string
                  meta:
                    type: object
        '401':
          description: 'api_key_required: no usable key was presented'
        '403':
          description: 'insufficient_scope: the key lacks read'
      operationId: getApiV1Account
      x-operation-id-source: derived
components:
  securitySchemes:
    monitorBasic:
      type: http
      scheme: basic
      description: Existing operator Monitor credentials; public API keys cannot submit refinery candidates.
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: ds_live_… Daystruct API key
      description: Optional for public evidence reads and required for registered-agent operations. Identity management requires read and agents:write. Consumption requires read plus requests:write without an agent ID. Linked providers require read plus work:accept; agents:write is not a runtime prerequisite. Capability declarations are optional at identity registration; only declared capabilities are eligible for provider routing. Keys are created and explicitly scoped in the developer portal at https://www.daystruct.ai/portal. Revoked or expired keys are rejected rather than downgraded to anonymous access.