Daystruct Entities API

openapi: 3.2.0
info:
  title: Daystruct Entities 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: Entities
paths:
  /api/v1/entities:
    get:
      summary: List and filter entities
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 100
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: databank
        in: query
        schema:
          type: string
      - name: type
        in: query
        schema:
          type: string
      - name: provider
        in: query
        schema:
          type: string
      - name: capability
        in: query
        schema:
          type: string
      - name: model_type
        in: query
        schema:
          type: string
      - name: min_context_window
        in: query
        schema:
          type: integer
      - name: lane
        in: query
        schema:
          type: string
      - name: X-Daystruct-Client-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
        description: Declared client identifier recorded in aggregate request telemetry.
      - name: X-Daystruct-Agent
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
        description: Optional declared agent name (1 to 80 printable characters on Data and Memory card requests). Card activity shows it as a self-named agent when no registered X-Daystruct-Agent-Id is verified.
      - name: X-Daystruct-Use-Case
        in: header
        required: false
        schema:
          type: string
          maxLength: 300
        description: Optional declared use case.
      - name: X-Daystruct-Agent-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Optional durable registered-agent identity. It is accepted only with an active API key linked to that active agent; verified use updates lastSeenAt and request attribution. When accepted, Daystruct returns the exact ID in X-Daystruct-Verified-Agent-Id. It is not a routing instruction.
      responses:
        '200':
          description: A bounded JSON envelope with pagination metadata.
        '400':
          description: Invalid query.
        '429':
          description: Rate limit exceeded.
      tags:
      - Entities
      operationId: getApiV1Entities
      x-operation-id-source: derived
  /api/v1/entities/{id}:
    get:
      summary: Get an entity
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Entity
        '404':
          description: Not found
      tags:
      - Entities
      operationId: getApiV1EntitiesById
      x-operation-id-source: derived
  /api/v1/entities/{id}/history:
    get:
      summary: List historical observations
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 100
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: X-Daystruct-Client-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
        description: Declared client identifier recorded in aggregate request telemetry.
      - name: X-Daystruct-Agent
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
        description: Optional declared agent name (1 to 80 printable characters on Data and Memory card requests). Card activity shows it as a self-named agent when no registered X-Daystruct-Agent-Id is verified.
      - name: X-Daystruct-Use-Case
        in: header
        required: false
        schema:
          type: string
          maxLength: 300
        description: Optional declared use case.
      - name: X-Daystruct-Agent-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Optional durable registered-agent identity. It is accepted only with an active API key linked to that active agent; verified use updates lastSeenAt and request attribution. When accepted, Daystruct returns the exact ID in X-Daystruct-Verified-Agent-Id. It is not a routing instruction.
      responses:
        '200':
          description: A bounded JSON envelope with pagination metadata.
        '400':
          description: Invalid query.
        '429':
          description: Rate limit exceeded.
      tags:
      - Entities
      operationId: getApiV1EntitiesByIdHistory
      x-operation-id-source: derived
  /api/v1/entities/{id}/facts:
    get:
      summary: List canonical facts and provenance
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 100
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: X-Daystruct-Client-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
        description: Declared client identifier recorded in aggregate request telemetry.
      - name: X-Daystruct-Agent
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
        description: Optional declared agent name (1 to 80 printable characters on Data and Memory card requests). Card activity shows it as a self-named agent when no registered X-Daystruct-Agent-Id is verified.
      - name: X-Daystruct-Use-Case
        in: header
        required: false
        schema:
          type: string
          maxLength: 300
        description: Optional declared use case.
      - name: X-Daystruct-Agent-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Optional durable registered-agent identity. It is accepted only with an active API key linked to that active agent; verified use updates lastSeenAt and request attribution. When accepted, Daystruct returns the exact ID in X-Daystruct-Verified-Agent-Id. It is not a routing instruction.
      responses:
        '200':
          description: A bounded JSON envelope with pagination metadata.
        '400':
          description: Invalid query.
        '429':
          description: Rate limit exceeded.
      tags:
      - Entities
      operationId: getApiV1EntitiesByIdFacts
      x-operation-id-source: derived
  /api/v1/entities/{id}/aliases:
    get:
      summary: List identity aliases
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 100
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: X-Daystruct-Client-Id
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
        description: Declared client identifier recorded in aggregate request telemetry.
      - name: X-Daystruct-Agent
        in: header
        required: false
        schema:
          type: string
          maxLength: 200
        description: Optional declared agent name (1 to 80 printable characters on Data and Memory card requests). Card activity shows it as a self-named agent when no registered X-Daystruct-Agent-Id is verified.
      - name: X-Daystruct-Use-Case
        in: header
        required: false
        schema:
          type: string
          maxLength: 300
        description: Optional declared use case.
      - name: X-Daystruct-Agent-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Optional durable registered-agent identity. It is accepted only with an active API key linked to that active agent; verified use updates lastSeenAt and request attribution. When accepted, Daystruct returns the exact ID in X-Daystruct-Verified-Agent-Id. It is not a routing instruction.
      responses:
        '200':
          description: A bounded JSON envelope with pagination metadata.
        '400':
          description: Invalid query.
        '429':
          description: Rate limit exceeded.
      tags:
      - Entities
      operationId: getApiV1EntitiesByIdAliases
      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.