Daystruct Discovery API

openapi: 3.2.0
info:
  title: Daystruct Discovery 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: Discovery
paths:
  /api/v1/project-development/plan:
    post:
      tags:
      - Discovery
      summary: Plan the next project development stage
      security: []
      description: 'Select up to four actual acquirable catalog releases for start/build/verify/resume. Outcomes remain caller-reported. No acquisition, execution, project storage or scheduled reminders. Send only a minimal caller-approved projection; keep full context, source and credentials local. MCP equivalent: plan_project_development.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - stage
              - goal
              properties:
                stage:
                  type: string
                  enum:
                  - start
                  - build
                  - verify
                  - resume
                goal:
                  type: string
                  minLength: 1
                  maxLength: 500
                stack:
                  type: array
                  maxItems: 12
                  items:
                    type: string
                    minLength: 1
                    maxLength: 60
                features:
                  type: array
                  maxItems: 4
                  items:
                    type: string
                    enum:
                    - auth
                    - webhooks
                    - browser
                    - dependencies
                hasContext:
                  type: boolean
                  default: false
                scopeNeedsDecision:
                  type: boolean
                  default: false
                currentSourceRevision:
                  type: string
                  pattern: ^[a-f0-9]{64}$
                contextSourceRevision:
                  type: string
                  pattern: ^[a-f0-9]{64}$
                pending:
                  type: array
                  maxItems: 20
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - taskId
                    - title
                    - action
                    properties:
                      taskId:
                        type: string
                        pattern: ^[A-Za-z0-9_-]{1,80}$
                      title:
                        type: string
                        minLength: 1
                        maxLength: 200
                      action:
                        type: string
                        enum:
                        - implement_and_verify
                        - verify_at_current_revision
                        - repair_and_retest
                        - resolve_issue
                        - review_scope_change
                checks:
                  type: array
                  maxItems: 20
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - id
                    - taskId
                    - title
                    - result
                    - sourceRevision
                    - artifactPath
                    - artifactDigest
                    properties:
                      id:
                        type: string
                        pattern: ^[A-Za-z0-9_-]{1,80}$
                      taskId:
                        type: string
                        pattern: ^[A-Za-z0-9_-]{1,80}$
                      title:
                        type: string
                        minLength: 1
                        maxLength: 200
                      result:
                        type: string
                        enum:
                        - passed
                        - failed
                        - unknown
                      sourceRevision:
                        type: string
                        pattern: ^[a-f0-9]{64}$
                      artifactPath:
                        type: string
                        minLength: 1
                        maxLength: 240
                      artifactDigest:
                        type: string
                        pattern: ^[a-f0-9]{64}$
                needs:
                  type: array
                  maxItems: 4
                  items:
                    type: string
                    minLength: 1
                    maxLength: 120
                  description: Optional explicit part needs; does not bypass exclusions in the project goal.
                impact:
                  type: object
                  additionalProperties: false
                  required:
                  - sourceRevision
                  - features
                  - coverageGaps
                  properties:
                    sourceRevision:
                      type: string
                      pattern: ^[a-f0-9]{64}$
                    features:
                      type: array
                      maxItems: 4
                      items:
                        type: string
                        enum:
                        - auth
                        - webhooks
                        - browser
                        - dependencies
                    coverageGaps:
                      type: array
                      maxItems: 20
                      items:
                        type: string
                        minLength: 1
                        maxLength: 200
                  description: Caller-reviewed minimal result from local change-impact selection. Keep diff, paths, manifest and commands local. Stale or unknown current revisions cannot support affected-feature recommendations.
      responses:
        '200':
          description: Recommendations with exact release metadata, gaps, evidence-referenced next actions and an optional return suggestion. executionVerified and projectComplete are false.
        '400':
          description: Unsupported or invalid project projection
        '405':
          description: Use POST
        '429':
          description: Read quota exceeded
      operationId: postApiV1ProjectDevelopmentPlan
      x-operation-id-source: derived
  /api/v1/frontier/guidance:
    get:
      tags:
      - Discovery
      summary: Read reviewed, unexpired Frontier guidance for an exact task/model scope
      parameters:
      - name: databank
        in: query
        required: true
        schema:
          type: string
      - name: taskFamily
        in: query
        required: false
        schema:
          type: string
      - name: model
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Scoped guidance and bounded evidence; no private fixtures
      operationId: getApiV1FrontierGuidance
      x-operation-id-source: derived
  /:
    get:
      tags:
      - Discovery
      summary: API introduction and discovery links
      responses:
        '200':
          description: Discovery document
      operationId: getRoot
      x-operation-id-source: derived
  /health:
    get:
      tags:
      - Discovery
      summary: Service and database readiness
      responses:
        '200':
          description: Healthy service
      operationId: getHealth
      x-operation-id-source: derived
  /status:
    get:
      tags:
      - Discovery
      summary: Sanitized public service and dataset status
      responses:
        '200':
          description: Public status
      operationId: getStatus
      x-operation-id-source: derived
  /manifest:
    get:
      tags:
      - Discovery
      summary: Machine-readable Daystruct capabilities and links
      responses:
        '200':
          description: Daystruct manifest
      operationId: getManifest
      x-operation-id-source: derived
  /.well-known/agent-card.json:
    get:
      tags:
      - Discovery
      summary: A2A 1.0 Agent Card for the read-only evidence agent
      responses:
        '200':
          description: A2A Agent Card
      operationId: getWellKnownAgentCardJson
      x-operation-id-source: derived
  /openapi.json:
    get:
      tags:
      - Discovery
      summary: This OpenAPI contract
      responses:
        '200':
          description: OpenAPI 3.1 document
      operationId: getOpenapiJson
      x-operation-id-source: derived
  /api/v1/network/pulse:
    get:
      tags:
      - Discovery
      summary: The network's pulse, aggregate and anonymised
      description: Request counts and outcomes over the last five minutes and day, by capability category and provider kind, settlement totals, public reads per minute, and the last forty requests as category, outcome, provider kind, cross-account flag, latency and attempt count. Never a request body, a requester, a provider identity, an account id, an evidence payload or a balance.
      responses:
        '200':
          description: Network pulse
      operationId: getApiV1NetworkPulse
      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.