Daystruct Capabilities API

openapi: 3.2.0
info:
  title: Daystruct Capabilities 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: Capabilities
paths:
  /api/v1/library:
    get:
      tags:
      - Capabilities
      summary: Search your saved and owned capabilities and bundles
      description: Account-scoped library. A saved resource is a reference, not an acquisition or execution grant. Search returns a shortlist of three by default. Private resources are visible only to their owner; revoked references remain unavailable placeholders.
      security:
      - apiKey: []
      parameters:
      - name: scope
        in: query
        schema:
          type: string
          enum:
          - saved
          - owned
          - library
          default: saved
      - name: q
        in: query
        schema:
          type: string
      - name: kind
        in: query
        schema:
          type: string
          enum:
          - capability
          - bundle
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Items, total matches and scope
        '401':
          description: Active account key required
      operationId: getApiV1Library
      x-operation-id-source: derived
  /api/v1/bundles:
    get:
      tags:
      - Capabilities
      summary: Discover public capability bundles
      parameters:
      - name: scope
        in: query
        schema:
          type: string
          enum:
          - owned
        description: With an account key, list your own bundles instead.
      description: Lists every public bundle, each with a kind and a state. Compatibility bundles (kind compatibility) are verified when the exact member set of their latest lock passed the bundle's integration suite, and unverified otherwise; each member carries its pinned version, digest and licensing. Curated bundles (kind curated, state curated) are compositions whose compatibility has not been tested. With scope=owned, lists only your own curated bundles.
      responses:
        '200':
          description: Compatibility and curated bundles, each with kind and state; performance is not inferred
      operationId: getApiV1Bundles
      x-operation-id-source: derived
  /api/v1/bundles/{id}:
    get:
      tags:
      - Capabilities
      summary: Resolve a bundle and its version-pinned members
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      description: Public bundles may be read anonymously. Private bundles require the owner's account key. Each member is rechecked for access and availability. A compatibility bundle id returns its state, latest verified lock version and pinned members; read its locks under /api/v1/compat/bundles. No code executes and no credits are charged.
      responses:
        '200':
          description: Bundle revision and members with version, digest, availability and profile
        '404':
          description: Unknown or inaccessible bundle
      operationId: getApiV1BundlesById
      x-operation-id-source: derived
  /api/v1/capabilities:
    get:
      tags:
      - Capabilities
      summary: Search and list capabilities (public, no key)
      description: 'Anonymous catalog search: no account, API key, MCP connection or credits. Example: GET /api/v1/capabilities?q=scan+a+repository+for+secrets&view=compact. meta carries total, offset, limit, nextOffset, a ready next URL and freshness {source, generatedAt, catalogUpdatedAt, maxAgeSeconds}; responses revalidate on every request (Cache-Control: public, no-cache, must-revalidate). Follow meta.next until it is null to read all entries. When nothing matches strongly, data is empty, meta.match_quality is no_strong_match and meta.nearest lists the closest capabilities. Each compact row carries reference (stable handle or ID), id, displayName, summary, category, useCases, tags, deliveryType, version, digest, publishedAt, updatedAt, availability, language, runsIn, compatibility, a limitation, licensing {status, basis}, priceCredits with priceUnit, access {discover, next}, next, profile (JSON), page (HTML) and evidence links; the profile holds the full record. Acquisition, downloads, execution and account operations need a scoped key and are named in access.next; searching never charges. Clients without a key share a per-IP request quota; 429 responses carry Retry-After. Published capabilities carry a stable public handle (@owner/slug), an internal cap_ ID and a routing ID; declared-but-unpublished capabilities are listed too, marked published: false. Public, no key. Filter with ?q=. Each source-package row carries a concise licensing summary: declaredLicense is what the publisher wrote, publicationStatus is what the policy found when the release published, and status is how it reads under the policy in force now. These are reported separately on purpose and are evidence against a configured policy, not legal advice; full receipts live on the capability profile. Licensing filters are optional, and a filtered response withholds entries that carry no licensing evidence rather than passing them through.'
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Task-oriented lexical ranking across identifiers, descriptions, contents and reviewed topics. Search matches include their terms; relevance is not proof of suitability.
      - name: view
        in: query
        required: false
        schema:
          type: string
          enum:
          - full
          - compact
        description: compact returns ranked descriptors with prerequisites, limitations, pricing and profile links, without test logs; eight per page unless limit is given. Default full preserves catalog metadata and returns at most 100 entries per page. Follow meta.next until null to enumerate the whole catalog.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
        description: Page size, 1-100. Out-of-range or non-integer values return 400 invalid_pagination.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
        description: Zero-based position in the ranked result set; follow meta.next or meta.nextOffset for the next page.
      - name: category
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated categories, case-insensitive, e.g. security,software.
      - name: delivery
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated delivery types: source_package, source_kit, hosted_function, provider_execution, declared.'
      - name: licenseStatus
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated: validated, review_required, blocked, legacy_unvalidated. Matches the interpretation in force under the current policy.'
      - name: licenseSpdx
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated SPDX identifiers the licensing evidence established, e.g. MIT,Apache-2.0. Not the publisher's declared string.
      - name: licenseEvidence
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated permission bases: verified-text, verified-upstream-api, declared, unverified.'
      - name: licensePolicyState
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated: current, policy_outdated, legacy_unvalidated. policy_outdated means the stored receipt was decided under a different policy version; it is not a re-evaluation.'
      - name: licenseUnresolved
        in: query
        required: false
        schema:
          type: string
          enum:
          - none
        description: none returns only releases with no unresolved licensing items.
      - name: licenseReciprocal
        in: query
        required: false
        schema:
          type: string
          enum:
          - exclude
          - only
        description: Whether reciprocal or copyleft terms were found in the licensing evidence.
      - name: bundleMembers
        in: query
        required: false
        schema:
          type: string
          enum:
          - all_validated
        description: Bundles whose pinned members each carried a validated receipt when the bundle published. Recorded evidence, not a live re-check of member state.
      responses:
        '200':
          description: Ranked capability page with pagination and freshness meta
        '400':
          description: invalid_pagination
        '429':
          description: Request quota exceeded; see Retry-After
      operationId: getApiV1Capabilities
      x-operation-id-source: derived
  /api/v1/capabilities/index:
    get:
      tags:
      - Capabilities
      summary: Slim catalog index of published parts
      description: 'One short row per published part: handle, one-line summary, delivery mode, version, price, digest, licensing status and its basis (receipt, legacy-reading, none, or not-distributed), the stored compatibility contract''s state and source, and the verified bundle locks that pin this exact version. Full evidence, test summaries and log links stay on the profile. Public; no credits charged.'
      responses:
        '200':
          description: Index rows, with field notes in meta
      operationId: getApiV1CapabilitiesIndex
      x-operation-id-source: derived
  /api/v1/capabilities/guides:
    get:
      operationId: capabilityTaskGuides
      summary: Evaluate curated capability workflows without an account
      description: Selected task guides with runnable read-only JavaScript examples, expected outputs, caller requirements, limitations, live release price/version/digest, licensing evidence and signup/key handoff. Uses public catalog visibility and task ranking. Empty results do not imply no match in the full catalog. No acquisition or execution occurs.
      security: []
      parameters:
      - name: q
        in: query
        schema:
          type: string
        description: Task sentence or tool name
      responses:
        '200':
          description: Envelope with matching curated guides and coverage limitations
      tags:
      - Capabilities
  /api/v1/capabilities/bundle:
    get:
      tags:
      - Capabilities
      summary: Prepare a group of capability profiles without execution or purchase
      parameters:
      - name: ref
        in: query
        required: true
        schema:
          type: array
          minItems: 1
          maxItems: 6
          items:
            type: string
        style: form
        explode: true
      responses:
        '200':
          description: Plan-only profiles, unresolved references and unchecked compatibility
        '400':
          description: Invalid reference list
      operationId: getApiV1CapabilitiesBundle
      x-operation-id-source: derived
  /api/v1/capabilities/{ref}/acquire:
    post:
      tags:
      - Capabilities
      summary: Acquire an inspected source implementation version
      description: Requires read and requests:write. Charges the offered price once per version, bounded by maxPriceCredits and the key ceiling. Exact version and digest required. Retries return the same account receipt. No code executes.
      security:
      - apiKey: []
      parameters:
      - name: ref
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - version
              - digest
              properties:
                version:
                  type: string
                digest:
                  type: string
                  pattern: ^[a-f0-9]{64}$
                maxPriceCredits:
                  type: integer
                  minimum: 0
                  maximum: 100000
                  default: 0
      responses:
        '200':
          description: Access receipt and artifact URL
        '400':
          description: Invalid version/digest or unsupported price
        '401':
          description: Authentication required
        '403':
          description: Insufficient scope
        '404':
          description: Package unavailable
        '409':
          description: Not inspected or version mismatch
        '503':
          description: Artifact integrity failure
      operationId: postApiV1CapabilitiesByRefAcquire
      x-operation-id-source: derived
  /api/v1/capabilities/{ref}/artifact:
    get:
      tags:
      - Capabilities
      summary: Download source acquired by this account
      description: 'Requires read scope and this account''s acquisition. JSON response: {data:{format,version,digest,artifact,instructions,licensing},meta}. data.artifact is itself a JSON string. Hash the decoded string''s exact UTF-8 bytes (no BOM, normalization or reserialization) before JSON.parse; compare to data.digest AND the digest selected before acquisition. Do not hash the HTTP envelope or the parsed/reserialized artifact. Embedded artifact.priceCredits is immutable submitted metadata, not the current offer or actual charge. v1 files contain path/content and optional encoding (utf8 default or base64). If a release advertises another format or blob references, stop and follow its documented delivery contract rather than treating references as inline files. Downloading never installs or executes code. Private and no-store.'
      x-delivery-contract:
        response: 'REST JSON: {data: {format, version, digest, artifact, instructions, licensing}, meta}'
        artifact: data.artifact is a JSON string, not a JSON object or a raw file download
        integrity:
          algorithm: sha256
          encoding: utf8
          input: The exact decoded data.artifact string, before JSON.parse; do not reserialize or normalize whitespace/newlines
          expected: Must equal both data.digest and the exact digest selected before acquisition
        files: After verification, parse the artifact. daystruct-source-v1 files have path/content and optional encoding (utf8 by default or base64). Preserve safe relative paths and decode according to encoding. If a release uses a different format or blob references, stop and follow its documented delivery contract; do not treat references as inline content.
        pricing: sourcePackage.priceCredits in the current public profile is the acquisition offer, including any disclosed service fee. artifact.priceCredits is immutable submitted metadata, not a current quote. The acquisition receipt's creditsChargedThisRequest is what this request spent; alreadyOwned may make it zero. Never modify artifact bytes to reconcile prices.
      x-codeSamples:
      - lang: JavaScript
        source: 'import { createHash } from ''node:crypto'';

          // response is a successful authenticated fetch of /artifact?version=...

          const { data } = await response.json();

          const actual = createHash(''sha256'').update(data.artifact, ''utf8'').digest(''hex'');

          if (actual !== data.digest || actual !== expectedDigest) throw new Error(''Digest mismatch'');

          const pack = JSON.parse(data.artifact); // only after verification

          '
      - lang: Python
        source: "import hashlib, json\n# response_body is the successful authenticated HTTP response body\ndata = json.loads(response_body)['data']\nactual = hashlib.sha256(data['artifact'].encode('utf-8')).hexdigest()\nif actual != data['digest'] or actual != expected_digest:\n    raise ValueError('Digest mismatch')\npack = json.loads(data['artifact']) # only after verification\n"
      security:
      - apiKey: []
      parameters:
      - name: version
        in: query
        description: Exact acquired version; defaults to the most recently acquired active version
        schema:
          type: string
      - name: ref
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Version, digest and private artifact string
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    required:
                    - format
                    - version
                    - digest
                    - artifact
                    properties:
                      format:
                        type: string
                        enum:
                        - daystruct-source-v1
                      version:
                        type: string
                      digest:
                        type: string
                        pattern: ^[a-f0-9]{64}$
                      artifact:
                        type: string
                        description: Exact JSON string whose UTF-8 bytes are SHA-256 hashed; not an object
                      instructions:
                        type: string
                      licensing:
                        type: object
                  meta:
                    type: object
        '401':
          description: Authentication required
        '404':
          description: No acquisition for this account
        '503':
          description: Artifact integrity failure
      operationId: getApiV1CapabilitiesByRefArtifact
      x-operation-id-source: derived
  /api/v1/capabilities/{ref}:
    get:
      tags:
      - Capabilities
      summary: Read one capability profile by any of its names
      description: ref is the cap_ internal ID, the @owner/slug handle (URL-encoded or raw), or the routing ID an agent declares. Source profiles include pricing (current offer and USD equivalent at the published top-up rate), trustVocabulary and structured useWith.integration. apiSurface documents public exports and validation for an exact digest when available; null means no published summary, not an empty API. deliveryType is canonical; deliveryMode is retained as a compatibility alias. Source developer.resultContract describes acquired bytes, not hosted invocation. Existing schemas, examples and identifiers remain under developer. Provider identities appear only for accounts that have claimed a public handle.
      parameters:
      - name: ref
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Capability profile
        '404':
          description: No published or declared capability matches
      operationId: getApiV1CapabilitiesByRef
      x-operation-id-source: derived
  /api/v1/capabilities/asset.validate_gltf/run:
    post:
      summary: Validate supplied glTF 2.0 JSON or GLB bytes and explicit resources; return…
      operationId: asset_validate_gltf
      description: 'data.status completed means the validator ran. Inspect result.status: valid, invalid, indeterminate. Missing resources, unsupported extensions or truncated reports are indeterminate, never valid. Rejected input is 400; execution failure is 503.'
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - format
              - dataBase64
              properties:
                format:
                  type: string
                  enum:
                  - gltf
                  - glb
                dataBase64:
                  type: string
                  maxLength: 700000
                  description: Canonical padded base64 of exact glTF JSON or GLB bytes
                resources:
                  type: array
                  maxItems: 32
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - uri
                    - dataBase64
                    properties:
                      uri:
                        type: string
                        minLength: 1
                        maxLength: 2048
                      dataBase64:
                        type: string
                        maxLength: 700000
      responses:
        '200':
          description: Execution completed; inspect data.result.status
        '400':
          description: Rejected input
        '401':
          description: Invalid or missing key
        '403':
          description: Insufficient scope
        '429':
          description: Capacity or rate limit
        '503':
          description: Execution failed or unavailable
      tags:
      - Capabilities
  /api/v1/capabilities/design.validate_token_refs/run:
    post:
      summary: Check supplied token JSON for duplicate definitions, missing exact references…
      operationId: design_validate_token_refs
      description: data contains invocationId, capabilityId, status, result, provenance and economics. completed means validation ran; inspect result.status (passed/failed). rejected is invalid input; failed is an execution failure.
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - documents
              properties:
                documents:
                  type: array
                  minItems: 1
                  maxItems: 20
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - name
                    - json
                    properties:
                      name:
                        type: string
                        minLength: 1
                        maxLength: 120
                      json:
                        type: string
                        maxLength: 500000
      responses:
        '200':
          description: Execution completed; inspect data.result.status
        '400':
          description: Rejected input
        '401':
          description: Invalid or missing key
        '403':
          description: Insufficient scope
        '429':
          description: Capacity or rate limit
        '503':
          description: Execution failed or unavailable
      tags:
      - Capabilities
  /api/v1/capabilities/web.extract_evidence/run:
    post:
      summary: Extract readable text from supplied HTML, with an explicit generic fallback and…
      operationId: web_extract_evidence
      description: data.status completed means extraction ran; inspect result.status (extracted or empty), result.extractor.selected and warnings. Empty is not proof there is no useful content. Rejected inputs return 400; extraction or worker failure returns 503.
      security:
      - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - html
              - sourceUrl
              - capturedAt
              properties:
                html:
                  type: string
                  maxLength: 1000000
                sourceUrl:
                  type: string
                  maxLength: 4096
                  description: HTTP(S) URL without credentials; caller asserted, never fetched
                capturedAt:
                  type: string
                  format: date-time
                  description: Valid UTC timestamp with optional three-digit milliseconds
                maxInputBytes:
                  type: integer
                  minimum: 1
                  maximum: 1000000
      responses:
        '200':
          description: Execution completed; inspect data.result.status
        '400':
          description: Rejected input
        '401':
          description: Invalid or missing key
        '403':
          description: Insufficient scope
        '429':
          description: Capacity or rate limit
        '503':
          description: Execution failed or unavailable
      tags:
      - Capabilities
  /api/v1/capabilities/companion.conversation_runtime/source:
    get:
      summary: 'Download source kit: Conversation runtime for voice companions'
      operationId: companion_conversation_runtime_source
      description: Download only. Daystruct does not execute, install or configure this code, and the download opens no microphone, window or paid provider. Your agent integrates it; you review it. Returns every file (or only those named by path) with sha256 hashes and the kit digest.
      security:
      - apiKey: []
      parameters:
      - name: path
        in: query
        required: false
        description: Return only these kit files, e.g. README.md. Repeatable.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      responses:
        '200':
          description: Kit files, hashes and digest
        '400':
          description: A requested path is not in the kit
        '401':
          description: Invalid or missing key
        '403':
          description: Key lacks read scope
        '503':
          description: Kit files do not match their pinned lock
      tags:
      - Capabilities
  /api/v1/capabilities/companion.controls/source:
    get:
      summary: 'Download source kit: Voice command routing for companions'
      operationId: companion_controls_source
      description: Download only. Daystruct does not execute, install or configure this code, and the download opens no microphone, window or paid provider. Your agent integrates it; you review it. Returns every file (or only those named by path) with sha256 hashes and the kit digest.
      security:
      - apiKey: []
      parameters:
      - name: path
        in: query
        required: false
        description: Return only these kit files, e.g. README.md. Repeatable.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      responses:
        '200':
          description: Kit files, hashes and digest
        '400':
          description: A requested path is not in the kit
        '401':
          description: Invalid or missing key
        '403':
          description: Key lacks read scope
        '503':
          description: Kit files do not match their pinned lock
      tags:
      - Capabilities
  /api/v1/capabilities/companion.desktop_overlay/source:
    get:
      summary: 'Download source kit: Always-on-top companion overlay'
      operationId: companion_desktop_overlay_source
      description: Download only. Daystruct does not execute, install or configure this code, and the download opens no microphone, window or paid provider. Your agent integrates it; you review it. Returns every file (or only those named by path) with sha256 hashes and the kit digest.
      security:
      - apiKey: []
      parameters:
      - name: path
        in: query
        required: false
        description: Return only these kit files, e.g. README.md. Repeatable.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      responses:
        '200':
          description: Kit files, hashes and digest
        '400':
          description: A requested path is not in the kit
        '401':
          description: Invalid or missing key
        '403':
          description: Key lacks read scope
        '503':
          description: Kit files do not match their pinned lock
      tags:
      - Capabilities
  /api/v1/capabilities/companion.avatar_presence/source:
    get:
      summary: 'Download source kit: VRM avatar presence'
      operationId: companion_avatar_presence_source
      description: Download only. Daystruct does not execute, install or configure this code, and the download opens no microphone, window or paid provider. Your agent integrates it; you review it. Returns every file (or only those named by path) with sha256 hashes and the kit digest.
      security:
      - apiKey: []
      parameters:
      - name: path
        in: query
        required: false
        description: Return only these kit files, e.g. README.md. Repeatable.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      responses:
        '200':
          description: Kit files, hashes and digest
        '400':
          description: A requested path is not in the kit
        '401':
          description: Invalid or missing key
        '403':
          description: Key lacks read scope
        '503':
          description: Kit files do not match their pinned lock
      tags:
      - Capabilities
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.