Daystruct Operator capability refinery API

openapi: 3.2.0
info:
  title: Daystruct Operator capability refinery 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: Operator capability refinery
paths:
  /api/v1/monitor/capability-refinery:
    get:
      tags:
      - Operator capability refinery
      summary: Discover durable repo intake, owner handles, builder status and remote commands
      security:
      - monitorBasic: []
      responses:
        '200':
          description: Candidate progress, blockers, summaries, checks and published URL in a data envelope
        '401':
          description: Monitor Basic authentication required
        '409':
          description: Idempotency conflict or action not allowed for this stage
      operationId: getApiV1MonitorCapabilityRefinery
      x-operation-id-source: derived
  /api/v1/monitor/capability-refinery/candidates:
    get:
      tags:
      - Operator capability refinery
      summary: List recent repository candidates
      security:
      - monitorBasic: []
      responses:
        '200':
          description: Candidate progress, blockers, summaries, checks and published URL in a data envelope
        '401':
          description: Monitor Basic authentication required
        '409':
          description: Idempotency conflict or action not allowed for this stage
      operationId: getApiV1MonitorCapabilityRefineryCandidates
      x-operation-id-source: derived
    post:
      tags:
      - Operator capability refinery
      summary: Save an open-source capability candidate without invoking the orchestrator model
      description: Acceptance persists a candidate even if model configuration or build budget is unavailable. Missing ownership remains needs_details. autoBuild dispatches through the existing isolated build/test/review engine. publishWhenReady is explicit. Never treat HTTP 202 as publication.
      security:
      - monitorBasic: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                repoUrl:
                  type: string
                  format: uri
                  description: Public https://github.com/owner/repository
                suggestedHandle:
                  type: string
                  description: '@owner/slug; dotted suggested slugs are normalized to hyphens'
                ownerHandle:
                  type: string
                slug:
                  type: string
                notes:
                  type: string
                  maxLength: 10000
                category:
                  type: string
                mode:
                  type: string
                  enum:
                  - source_package
                sourceRef:
                  type: string
                sourcePaths:
                  type: array
                  items:
                    type: string
                  maxItems: 30
                conversationRef:
                  type: string
                idempotencyKey:
                  type: string
                  minLength: 8
                  maxLength: 120
                autoBuild:
                  type: boolean
                  default: true
                publishWhenReady:
                  type: boolean
                  default: false
                maxCostUsd:
                  type: number
                  minimum: 3
                  maximum: 10
                  default: 3
              required:
              - repoUrl
              - notes
              - idempotencyKey
      responses:
        '200':
          description: Candidate progress, blockers, summaries, checks and published URL in a data envelope
        '202':
          description: Durably accepted; poll the returned candidate link
        '401':
          description: Monitor Basic authentication required
        '409':
          description: Idempotency conflict or action not allowed for this stage
      operationId: postApiV1MonitorCapabilityRefineryCandidates
      x-operation-id-source: derived
  /api/v1/monitor/capability-refinery/candidates/{id}:
    get:
      tags:
      - Operator capability refinery
      summary: Read candidate progress, blocker, next action, summary and publication
      security:
      - monitorBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^ci_[a-f0-9-]+$
      responses:
        '200':
          description: Candidate progress, blockers, summaries, checks and published URL in a data envelope
        '401':
          description: Monitor Basic authentication required
        '409':
          description: Idempotency conflict or action not allowed for this stage
      operationId: getApiV1MonitorCapabilityRefineryCandidatesById
      x-operation-id-source: derived
  /api/v1/monitor/capability-refinery/candidates/{id}/retry:
    post:
      tags:
      - Operator capability refinery
      summary: retry a capability candidate
      description: Explicitly authorize a new build attempt and reservation after resolving the prior failure. Reuse action idempotencyKey only for exact retries.
      security:
      - monitorBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^ci_[a-f0-9-]+$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotencyKey:
                  type: string
                  minLength: 8
                  maxLength: 120
              required:
              - idempotencyKey
      responses:
        '200':
          description: Candidate progress, blockers, summaries, checks and published URL in a data envelope
        '401':
          description: Monitor Basic authentication required
        '409':
          description: Idempotency conflict or action not allowed for this stage
      operationId: postApiV1MonitorCapabilityRefineryCandidatesByIdRetry
      x-operation-id-source: derived
  /api/v1/monitor/capability-refinery/candidates/{id}/revise:
    post:
      tags:
      - Operator capability refinery
      summary: revise a capability candidate
      description: Existing build tests and exact-digest publication checks remain enforced.
      security:
      - monitorBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^ci_[a-f0-9-]+$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                repoUrl:
                  type: string
                  format: uri
                  description: Public https://github.com/owner/repository
                suggestedHandle:
                  type: string
                  description: '@owner/slug; dotted suggested slugs are normalized to hyphens'
                ownerHandle:
                  type: string
                slug:
                  type: string
                notes:
                  type: string
                  maxLength: 10000
                category:
                  type: string
                mode:
                  type: string
                  enum:
                  - source_package
                sourceRef:
                  type: string
                sourcePaths:
                  type: array
                  items:
                    type: string
                  maxItems: 30
                conversationRef:
                  type: string
                idempotencyKey:
                  type: string
                  minLength: 8
                  maxLength: 120
                autoBuild:
                  type: boolean
                  default: true
                publishWhenReady:
                  type: boolean
                  default: false
                maxCostUsd:
                  type: number
                  minimum: 3
                  maximum: 10
                  default: 3
              required:
              - idempotencyKey
      responses:
        '200':
          description: Candidate progress, blockers, summaries, checks and published URL in a data envelope
        '401':
          description: Monitor Basic authentication required
        '409':
          description: Idempotency conflict or action not allowed for this stage
      operationId: postApiV1MonitorCapabilityRefineryCandidatesByIdRevise
      x-operation-id-source: derived
  /api/v1/monitor/capability-refinery/candidates/{id}/cancel:
    post:
      tags:
      - Operator capability refinery
      summary: cancel a capability candidate
      description: Existing build tests and exact-digest publication checks remain enforced.
      security:
      - monitorBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^ci_[a-f0-9-]+$
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties: {}
              required: []
      responses:
        '200':
          description: Candidate progress, blockers, summaries, checks and published URL in a data envelope
        '401':
          description: Monitor Basic authentication required
        '409':
          description: Idempotency conflict or action not allowed for this stage
      operationId: postApiV1MonitorCapabilityRefineryCandidatesByIdCancel
      x-operation-id-source: derived
  /api/v1/monitor/capability-refinery/candidates/{id}/publish:
    post:
      tags:
      - Operator capability refinery
      summary: publish a capability candidate
      description: Existing build tests and exact-digest publication checks remain enforced.
      security:
      - monitorBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^ci_[a-f0-9-]+$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                digest:
                  type: string
                  pattern: ^[a-f0-9]{64}$
              required:
              - digest
      responses:
        '200':
          description: Candidate progress, blockers, summaries, checks and published URL in a data envelope
        '401':
          description: Monitor Basic authentication required
        '409':
          description: Idempotency conflict or action not allowed for this stage
      operationId: postApiV1MonitorCapabilityRefineryCandidatesByIdPublish
      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.