Daystruct Compatibility API

openapi: 3.2.0
info:
  title: Daystruct Compatibility 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: Compatibility
  description: 'Compatibility contracts: check whether capabilities work together, read verified bundle locks, and verify a set locally. Public and read-only apart from verify reports.'
paths:
  /api/v1/compat/check:
    post:
      tags:
      - Compatibility
      summary: Check whether a set of capabilities works together
      description: 'Send capabilities (id and semver range, up to 25) or a bundle reference (bundle@latest-verified or bundle@x.y.z), not both. Minimal runtime/platform example: {capabilities:[{id:''@daystruct/security-gitleaks'',range:''1.0.0''}],project:{runtime:{node:''24.20.0''},platform:''linux''}}. Use your actual runtime/platform. This can produce project-checked, covering only supplied fields, not execution; include supported dependency fields when relevant. Never send source code. Optionally add a verifyReportId from a passing local verify of this exact set. Returns resolved versions/digests, conflicts, advisories, licensing and verified-lock memberships. Membership alone does not make your project verified. Public; no account needed and no credits charged.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                capabilities:
                  type: array
                  minItems: 1
                  maxItems: 25
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - id
                    properties:
                      id:
                        type: string
                        example: '@daystruct/security-gitleaks'
                      range:
                        type: string
                        default: '*'
                bundle:
                  type: string
                  example: security-scanners@latest-verified
                project:
                  type: object
                  description: 'Project manifest: runtime and declared packages'
                verifyReportId:
                  type: string
                  pattern: ^cvr_[a-f0-9]{24}$
      responses:
        '200':
          description: Resolved set, conflicts, advisories, member licensing, verified-lock memberships and check scope
        '400':
          description: Malformed request
        '404':
          description: Unknown capability or bundle
        '429':
          description: Rate limited
      operationId: postApiV1CompatCheck
      x-operation-id-source: derived
  /api/v1/compat/verify-kit:
    post:
      tags:
      - Compatibility
      summary: Get a kit to verify an exact set in your own environment
      description: For exact member versions (up to 25), returns the set digest, the member digests and the steps to run their tests locally and produce a verify report. Nothing runs on Daystruct.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - members
              properties:
                members:
                  type: array
                  minItems: 1
                  maxItems: 25
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - id
                    - version
                    properties:
                      id:
                        type: string
                      version:
                        type: string
                        pattern: ^\d+\.\d+\.\d+$
      responses:
        '200':
          description: Set digest, member digests and kit steps
        '400':
          description: Malformed request
        '404':
          description: Unknown capability or version
      operationId: postApiV1CompatVerifyKit
      x-operation-id-source: derived
  /api/v1/compat/verify-reports:
    post:
      tags:
      - Compatibility
      summary: Submit a local verify report
      description: A strict report of pass, fail or incomplete for one set digest, with per-member test counts and an environment summary. It carries no free text. A passing report can be cited by verifyReportId in compat.check. An API key is optional; with one, the report is attributed to your account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - schemaVersion
              - setDigest
              - result
              - members
              properties:
                schemaVersion:
                  type: integer
                  enum:
                  - 1
                setDigest:
                  type: string
                result:
                  type: string
                  enum:
                  - pass
                  - fail
                  - incomplete
                members:
                  type: array
                  minItems: 1
                  maxItems: 25
      responses:
        '201':
          description: Report recorded, with its cvr_ id
        '400':
          description: Malformed report
      operationId: postApiV1CompatVerifyReports
      x-operation-id-source: derived
    get:
      tags:
      - Compatibility
      summary: Read the verify reports for one set
      parameters:
      - name: set
        in: query
        required: true
        schema:
          type: string
        description: The set digest
      responses:
        '200':
          description: Reports for the set, newest first
      operationId: getApiV1CompatVerifyReports
      x-operation-id-source: derived
  /api/v1/compat/bundles:
    get:
      tags:
      - Compatibility
      summary: List compatibility bundles and their state
      responses:
        '200':
          description: Each bundle's id, description, state (verified or unverified), latest verified lock version and flags
      operationId: getApiV1CompatBundles
      x-operation-id-source: derived
  /api/v1/compat/bundles/{id}:
    get:
      tags:
      - Compatibility
      summary: Read a compatibility bundle
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Manifest, latest verified lock with member licensing, state, flags (failed float, awaiting approval, advisory) and recent floats
        '404':
          description: Unknown bundle
      operationId: getApiV1CompatBundlesById
      x-operation-id-source: derived
  /api/v1/compat/bundles/{id}/locks:
    get:
      tags:
      - Compatibility
      summary: List a bundle's verified locks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Every lock, with exact member versions, digests and licensing
        '404':
          description: Unknown bundle
      operationId: getApiV1CompatBundlesByIdLocks
      x-operation-id-source: derived
  /api/v1/compat/bundles/{id}/locks/{version}:
    get:
      tags:
      - Compatibility
      summary: Read one verified lock
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: version
        in: path
        required: true
        schema:
          type: string
          example: 1.0.1
      responses:
        '200':
          description: 'The lock: member versions, digests, licensing, integration run and set digest'
        '404':
          description: Unknown bundle or lock
      operationId: getApiV1CompatBundlesByIdLocksByVersion
      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.