Daystruct Data API

openapi: 3.2.0
info:
  title: Daystruct Data 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: Data
paths:
  /a2a:
    post:
      tags:
      - Data
      summary: Read evidence through A2A JSON-RPC
      responses:
        '200':
          description: A2A JSON-RPC response
      operationId: postA2a
      x-operation-id-source: derived
  /mcp:
    post:
      tags:
      - Data
      summary: Use public evidence and key-scoped request/provider MCP tools over Streamable…
      responses:
        '200':
          description: MCP response
      operationId: postMcp
      x-operation-id-source: derived
  /api/v1/software/answer:
    get:
      tags:
      - Data
      summary: Resolve several paired software questions and a compatibility check in one…
      description: Repeat package and api in matching order (up to four pairs). Optional runtime_package, runtime, and runtime_version must be supplied together.
      parameters:
      - name: package
        in: query
        required: true
        description: Repeat in the same order as api, for example next then react.
        schema:
          type: array
          maxItems: 4
          items:
            type: string
        example:
        - next
        - react
        style: form
        explode: true
      - name: api
        in: query
        required: true
        description: Claim target paired positionally with package.
        schema:
          type: array
          maxItems: 4
          items:
            type: string
        example:
        - cache components
        - server components
        style: form
        explode: true
      - name: runtime_package
        in: query
        required: false
        schema:
          type: string
      - name: runtime
        in: query
        required: false
        schema:
          type: string
      - name: runtime_version
        in: query
        required: false
        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.
      operationId: getApiV1SoftwareAnswer
      x-operation-id-source: derived
  /api/v1/databanks/{slug}/vulnerability:
    get:
      tags:
      - Data
      summary: Look up one vulnerability by its identifier
      description: 'Defined for the cybersecurity databank. The entity here is the vulnerability, so this is the entry point for a caller that holds an identifier rather than a package it is running -- every other route requires a package name. Returns the affected package and range, the version that fixes it, severity, and exploitation status. Fields are returned as claims carrying their own authority: status ''known'' with authority ''exclusive'' means Daystruct has evidence for the value, while status ''unknown'' with authority ''non_exclusive'' means Daystruct has no evidence either way and the answer does not contradict or supersede what the caller already knows. Exploitation is never reported as false, because the known-exploited catalog held here is a partial slice.'
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        example: cybersecurity
      - name: cve
        in: query
        required: true
        description: Vulnerability identifier. Case-insensitive.
        schema:
          type: string
        example: CVE-2024-0001
      - 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.
      operationId: getApiV1DatabanksBySlugVulnerability
      x-operation-id-source: derived
  /api/v1/databanks/{slug}/exposure:
    get:
      tags:
      - Data
      summary: Resolve which known vulnerabilities affect a specific version of a package
      description: Defined for the cybersecurity databank. Answers the question a maintainer actually asks -- I am running this version, what affects me -- rather than returning affected ranges to interpret. Findings are ordered worst first, with exploited-in-the-wild ahead of a higher score. Advisories whose affected range could not be read are returned under undetermined and are never counted as unaffected.
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        example: cybersecurity
      - name: package
        in: query
        required: true
        description: Package name as the advisory names it.
        schema:
          type: string
        example: vllm
      - name: version
        in: query
        required: true
        description: The version you are running.
        schema:
          type: string
        example: 0.11.2
      - name: ecosystem
        in: query
        required: false
        description: Narrows to one registry when a package name is reused across them.
        schema:
          type: string
        example: pip
      - 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.
      operationId: getApiV1DatabanksBySlugExposure
      x-operation-id-source: derived
  /api/v1/databanks/{slug}/models:
    get:
      tags:
      - Data
      summary: Select models that satisfy stated constraints
      description: Defined for the ai-infrastructure databank. Returns candidates ordered by input price ascending then larger context window, each with the corroboration behind its record. Prices are per million tokens. A model with no published price is returned under undetermined rather than excluded, so an unpriced model never reads as a disqualified one. Repeat capability to require several.
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        example: ai-infrastructure
      - name: min_context_window
        in: query
        required: false
        schema:
          type: integer
        example: 128000
      - name: capability
        in: query
        required: false
        description: Repeat to require several capabilities.
        schema:
          type: array
          items:
            type: string
        example:
        - reasoning
        - tool-use
        style: form
        explode: true
      - name: max_input_price
        in: query
        required: false
        description: Ceiling in dollars per million input tokens.
        schema:
          type: number
        example: 1
      - name: max_output_price
        in: query
        required: false
        schema:
          type: number
        example: 5
      - name: provider
        in: query
        required: false
        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.
      operationId: getApiV1DatabanksBySlugModels
      x-operation-id-source: derived
  /api/v1/databanks/{slug}/support:
    get:
      tags:
      - Data
      summary: Resolve whether a version of a product is still supported, as of now
      description: Defined for the software-development databank. Only published lifecycle dates are stored; support status is computed at request time, because a stored boolean is wrong the day support lapses and says nothing about when it was evaluated. A release line with no published end-of-life resolves to undetermined rather than supported.
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        example: software-development
      - name: product
        in: query
        required: true
        schema:
          type: string
        example: nodejs
      - name: version
        in: query
        required: true
        schema:
          type: string
        example: 22.3.1
      - 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.
      operationId: getApiV1DatabanksBySlugSupport
      x-operation-id-source: derived
  /api/v1/databanks/{slug}/context-contract:
    get:
      tags:
      - Data
      summary: Get a databank context-packet, temporal, identity, and dimension contract
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Consumer-facing context-packet contract
        '404':
          description: No context contract for this databank
      operationId: getApiV1DatabanksBySlugContextContract
      x-operation-id-source: derived
  /api/v1/events:
    get:
      tags:
      - Data
      summary: Consume the durable canonical change feed
      description: Returns events oldest first. Persist meta.cursor.next and send it as after. Delivery is at least once; deduplicate by event id.
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 100
      - name: after
        in: query
        schema:
          type: string
      - name: since
        in: query
        schema:
          type: string
      - name: until
        in: query
        schema:
          type: string
      - name: entity_id
        in: query
        schema:
          type: string
      - name: entity_type
        in: query
        schema:
          type: string
      - name: provider
        in: query
        schema:
          type: string
      - name: field
        in: query
        schema:
          type: string
      - name: significance
        in: query
        schema:
          type: string
      - name: source_id
        in: query
        schema:
          type: string
      - name: type
        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.
      operationId: getApiV1Events
      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.