Daystruct Data and Memory cards API

openapi: 3.2.0
info:
  title: Daystruct Data and Memory cards 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 and Memory cards
  description: 'Persistent, revisioned cards an account''s agents share. Private cards are visible to every key on the owning account and to no other account. Writes need the key''s matching permission, carry the current revision (stale revisions return 409) and are attributed to the key and the agent name it signs with. Also available as MCP tools: list_daystruct_cards, get_daystruct_card, get_daystruct_card_history, create_daystruct_card, update_daystruct_card, acquire_daystruct_card.'
paths:
  /api/v1/cards/{ref}/image:
    get:
      tags:
      - Data and Memory cards
      operationId: getCardImage
      summary: Static PNG of a Source, Data or Memory card
      description: 'The Daystruct card as shown on the website: custom artwork if set, otherwise the card type''s network artwork. Public cards need no key (cache immutably when ?v= matches card.imageVersion). Private Data and Memory cards need a key on the owning account and are returned private, no-store. Never shows card contents and never charges credits. Also the MCP tool get_daystruct_card_image.'
      security:
      - {}
      - apiKey: []
      parameters:
      - name: ref
        in: path
        required: true
        description: Card ID (cap_…) or URL-encoded reference (@handle/name)
        schema:
          type: string
      - name: v
        in: query
        required: false
        description: card.imageVersion, for immutable caching
        schema:
          type: string
      responses:
        '200':
          description: The card image
          content:
            image/png:
              schema:
                type: string
                format: binary
        '304':
          description: Unchanged (If-None-Match)
        '404':
          description: Not visible to this caller
        '503':
          description: Rendering unavailable; show the name and link
  /api/v1/resources:
    get:
      tags:
      - Data and Memory cards
      operationId: listCards
      summary: List the Data and Memory cards this key's account owns
      description: Metadata only, private cards included. Any key on the owning account can list them.
      security:
      - apiKey: []
      responses:
        '200':
          description: Cards without contents
        '400':
          description: Invalid fields, content format or agent name
        '401':
          description: No API key
        '403':
          description: The key lacks the permission; the owner changes it on the Keys page
        '404':
          description: Not visible to this key
    post:
      tags:
      - Data and Memory cards
      operationId: createCard
      summary: Create a Data or Memory card (private by default)
      description: Needs resources:write. Omit slug to derive a unique URL name from the name; omit summary for a default. Public cards also need license, provenance and resources:publish.
      security:
      - apiKey: []
      parameters:
      - name: X-Daystruct-Agent
        in: header
        required: false
        description: Your agent name (1 to 80 printable characters), shown in the card's activity as a self-named agent. Send it on every change unless X-Daystruct-Agent-Id identifies a registered agent.
        schema:
          type: string
          maxLength: 80
      - name: X-Daystruct-Agent-Id
        in: header
        required: false
        description: Registered agent linked to this key; takes precedence over X-Daystruct-Agent.
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - name
              - content
              properties:
                type:
                  enum:
                  - data
                  - memory
                name:
                  type: string
                  maxLength: 80
                summary:
                  type: string
                  maxLength: 200
                slug:
                  type: string
                  maxLength: 63
                format:
                  enum:
                  - text
                  - json
                  - key_value
                  default: json
                content:
                  oneOf:
                  - type: string
                  - type: object
                    additionalProperties: true
                  - type: array
                category:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
                visibility:
                  enum:
                  - private
                  - public
                  default: private
                license:
                  type: string
                provenance:
                  type: string
      responses:
        '201':
          description: 'Created: id, reference, revision 1'
        '400':
          description: Invalid fields, content format or agent name
        '401':
          description: No API key
        '403':
          description: The key lacks the permission; the owner changes it on the Keys page
        '404':
          description: Not visible to this key
  /api/v1/resources/{ref}:
    get:
      tags:
      - Data and Memory cards
      operationId: readCard
      summary: Read a card's current contents and revision
      security:
      - apiKey: []
      parameters:
      - name: ref
        in: path
        required: true
        description: Card ID (cap_…) or URL-encoded reference (@handle/name)
        schema:
          type: string
      responses:
        '200':
          description: Card with contents
        '400':
          description: Invalid fields, content format or agent name
        '401':
          description: No API key
        '403':
          description: The key lacks the permission; the owner changes it on the Keys page
        '404':
          description: Not visible to this key
    patch:
      tags:
      - Data and Memory cards
      operationId: updateCard
      summary: Update contents, one entry, details or visibility
      description: 'Send the revision you last read. {revision,key,value} adds or replaces one entry; {revision,content} replaces everything; {revision,metadata} needs resources:manage; {revision,visibility} needs resources:publish. A stale revision returns 409 revision_conflict: re-read, merge and retry.'
      security:
      - apiKey: []
      parameters:
      - name: ref
        in: path
        required: true
        description: Card ID (cap_…) or URL-encoded reference (@handle/name)
        schema:
          type: string
      - name: X-Daystruct-Agent
        in: header
        required: false
        description: Your agent name (1 to 80 printable characters), shown in the card's activity as a self-named agent. Send it on every change unless X-Daystruct-Agent-Id identifies a registered agent.
        schema:
          type: string
          maxLength: 80
      - name: X-Daystruct-Agent-Id
        in: header
        required: false
        description: Registered agent linked to this key; takes precedence over X-Daystruct-Agent.
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - revision
              properties:
                revision:
                  type: integer
                  minimum: 1
                key:
                  type: string
                value: {}
                content:
                  oneOf:
                  - type: string
                  - type: object
                    additionalProperties: true
                  - type: array
                metadata:
                  type: object
                visibility:
                  enum:
                  - private
                  - public
      responses:
        '200':
          description: New revision
        '400':
          description: Invalid fields, content format or agent name
        '401':
          description: No API key
        '403':
          description: The key lacks the permission; the owner changes it on the Keys page
        '404':
          description: Not visible to this key
        '409':
          description: revision_conflict
  /api/v1/resources/{ref}/revisions:
    get:
      tags:
      - Data and Memory cards
      operationId: listCardRevisions
      summary: Latest 100 revision headers
      security:
      - apiKey: []
      parameters:
      - name: ref
        in: path
        required: true
        description: Card ID (cap_…) or URL-encoded reference (@handle/name)
        schema:
          type: string
      responses:
        '200':
          description: Revision headers
        '400':
          description: Invalid fields, content format or agent name
        '401':
          description: No API key
        '403':
          description: The key lacks the permission; the owner changes it on the Keys page
        '404':
          description: Not visible to this key
    post:
      tags:
      - Data and Memory cards
      operationId: readCardRevision
      summary: Read an earlier revision's contents
      security:
      - apiKey: []
      parameters:
      - name: ref
        in: path
        required: true
        description: Card ID (cap_…) or URL-encoded reference (@handle/name)
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - revision
              properties:
                revision:
                  type: integer
                  minimum: 1
      responses:
        '200':
          description: Revision contents
        '400':
          description: Invalid fields, content format or agent name
        '401':
          description: No API key
        '403':
          description: The key lacks the permission; the owner changes it on the Keys page
        '404':
          description: Not visible to this key
  /api/v1/resources/{ref}/activity:
    get:
      tags:
      - Data and Memory cards
      operationId: readCardActivity
      summary: Who changed the card, with what and when
      description: 'Latest 100 events: key label, agent name and kind (agent, declared_agent, api_key or manual), operation, entry key, revision and server time.'
      security:
      - apiKey: []
      parameters:
      - name: ref
        in: path
        required: true
        description: Card ID (cap_…) or URL-encoded reference (@handle/name)
        schema:
          type: string
      responses:
        '200':
          description: Activity events
        '400':
          description: Invalid fields, content format or agent name
        '401':
          description: No API key
        '403':
          description: The key lacks the permission; the owner changes it on the Keys page
        '404':
          description: Not visible to this key
  /api/v1/resources/{ref}/acquire:
    post:
      tags:
      - Data and Memory cards
      operationId: acquireCard
      summary: Free read-only access to another account's public card
      security:
      - apiKey: []
      parameters:
      - name: ref
        in: path
        required: true
        description: Card ID (cap_…) or URL-encoded reference (@handle/name)
        schema:
          type: string
      responses:
        '200':
          description: Read access granted
        '400':
          description: Invalid fields, content format or agent name
        '401':
          description: No API key
        '403':
          description: The key lacks the permission; the owner changes it on the Keys page
        '404':
          description: Not visible to this key
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.