Daystruct Registered Agents API

openapi: 3.2.0
info:
  title: Daystruct Registered Agents 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: Registered Agents
  description: API-key-linked developer agent identity and declared capabilities. No routing or task dispatch is provided.
paths:
  /api/v1/agents:
    get:
      tags:
      - Registered Agents
      summary: List agents linked to the authenticating API key
      description: Returns only identities explicitly linked to this key, even when another key belongs to the same account.
      security:
      - apiKey: []
      x-daystruct-required-scopes:
      - read
      - agents:write
      responses:
        '200':
          description: Key-linked registered agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeveloperAgentListEnvelope'
        '401':
          description: A valid API key is required
        '403':
          description: The key lacks read or agents:write
      operationId: getApiV1Agents
      x-operation-id-source: derived
  /api/v1/agents/register:
    post:
      tags:
      - Registered Agents
      summary: Register and link a durable developer agent identity
      description: 'An exact retry from the already-linked key returns the stable identity, including when the account is at its non-archived registration limit. Another key cannot claim the same account slug, archived slugs remain reserved, and a differing registration for that slug conflicts. Credentials rotate without moving the identity: the account owner authorizes additional keys for an existing agent in the developer portal, and a key can never link itself. Capabilities remain declared and routable is always false.'
      security:
      - apiKey: []
      x-daystruct-required-scopes:
      - read
      - agents:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeveloperAgentRegistration'
      responses:
        '200':
          description: Exact retry by the linked key; stable identity returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeveloperAgentRegistrationEnvelope'
        '201':
          description: Registered identity created and linked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeveloperAgentRegistrationEnvelope'
        '400':
          description: Invalid structured registration
        '401':
          description: A valid API key is required
        '403':
          description: The key lacks read or agents:write
        '409':
          description: The account slug conflicts or the non-archived registration limit was reached
      operationId: postApiV1AgentsRegister
      x-operation-id-source: derived
  /api/v1/agents/{id}:
    get:
      tags:
      - Registered Agents
      summary: Read a registered agent linked to this API key
      security:
      - apiKey: []
      x-daystruct-required-scopes:
      - read
      - agents:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Key-linked registered agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeveloperAgentEnvelope'
        '401':
          description: A valid API key is required
        '403':
          description: The key lacks read or agents:write
        '404':
          description: Not found, archived, or not linked to this key
      operationId: getApiV1AgentsById
      x-operation-id-source: derived
    patch:
      tags:
      - Registered Agents
      summary: Update a registered agent linked to this API key
      description: Updates lifecycle state, descriptive fields, or declared capabilities. The slug and owner are immutable; this operation does not make the agent routable. Archived identities are owner-history records and cannot be changed by API keys.
      security:
      - apiKey: []
      x-daystruct-required-scopes:
      - read
      - agents:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeveloperAgentUpdate'
      responses:
        '200':
          description: Registered agent updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeveloperAgentEnvelope'
        '400':
          description: Invalid structured update
        '401':
          description: A valid API key is required
        '403':
          description: The key lacks read or agents:write
        '404':
          description: Not found, archived, or not linked to this key
      operationId: patchApiV1AgentsById
      x-operation-id-source: derived
components:
  schemas:
    DeveloperAgentCapability:
      type: object
      additionalProperties: false
      required:
      - id
      - description
      - state
      properties:
        id:
          type: string
          minLength: 3
          maxLength: 100
          pattern: ^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$
        description:
          type: string
          minLength: 1
          maxLength: 500
        state:
          type: string
          const: declared
    DeveloperAgentUpdate:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        displayName:
          type: string
          minLength: 1
          maxLength: 80
        description:
          type: string
          minLength: 1
          maxLength: 1000
        status:
          type: string
          enum:
          - active
          - disabled
          description: API keys cannot archive an identity or reactivate an archived identity.
        capabilities:
          type: array
          minItems: 0
          maxItems: 32
          uniqueItems: true
          description: One structured declaration per unique capability ID.
          items:
            $ref: '#/components/schemas/DeveloperAgentCapabilityDeclaration'
    DeveloperAgentCapabilityDeclaration:
      type: object
      additionalProperties: false
      required:
      - id
      - description
      properties:
        id:
          type: string
          minLength: 3
          maxLength: 100
          pattern: ^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$
          example: knowledge.query
        description:
          type: string
          minLength: 1
          maxLength: 500
          example: Queries provenance-backed Daystruct evidence.
    DeveloperAgentEnvelope:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          $ref: '#/components/schemas/DeveloperAgent'
        meta:
          type: object
    DeveloperAgentListEnvelope:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DeveloperAgent'
        meta:
          type: object
    DeveloperAgentRegistration:
      type: object
      additionalProperties: false
      required:
      - slug
      - displayName
      - description
      properties:
        slug:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
        displayName:
          type: string
          minLength: 1
          maxLength: 80
        description:
          type: string
          minLength: 1
          maxLength: 1000
        status:
          type: string
          enum:
          - active
          - disabled
          default: active
          description: API keys may create active or disabled identities; archival is owner-session only.
        capabilities:
          type: array
          minItems: 0
          maxItems: 32
          uniqueItems: true
          description: One structured declaration per unique capability ID.
          items:
            $ref: '#/components/schemas/DeveloperAgentCapabilityDeclaration'
    DeveloperAgent:
      type: object
      additionalProperties: false
      required:
      - id
      - ownerAccountId
      - slug
      - displayName
      - description
      - status
      - capabilities
      - routable
      - createdAt
      - updatedAt
      - lastSeenAt
      - keyAssociation
      properties:
        id:
          type: string
          format: uuid
        ownerAccountId:
          type: string
          format: uuid
        slug:
          type: string
        displayName:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - active
          - disabled
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/DeveloperAgentCapability'
        routable:
          type: boolean
          const: false
          description: Always false. Registration creates identity and attribution only; it does not enable routing or task dispatch.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        lastSeenAt:
          type:
          - string
          - 'null'
          format: date-time
        keyAssociation:
          type: object
          additionalProperties: false
          required:
          - apiKeyId
          - linked
          properties:
            apiKeyId:
              type: string
              format: uuid
            linked:
              type: boolean
              const: true
    DeveloperAgentRegistrationEnvelope:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          $ref: '#/components/schemas/DeveloperAgent'
        meta:
          type: object
          required:
          - created
          properties:
            created:
              type: boolean
  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.