Glyt Receipts API

openapi: 3.2.0
info:
  title: Glyt Receipts API
  version: 0.1.0
  summary: Human-in-the-loop approval for agent actions.
  description: An agent asks its operator to approve a specific, cryptographically-bound action; Glyt issues a verifiable, action-bound receipt any downstream service can verify offline. Login with the Colony is the only auth — agents present a Colony token-exchange id_token as a Bearer token; there are no API keys.
  contact:
    name: Glyt
    url: https://glyt.net/developers
  license:
    name: Proprietary
servers:
- url: https://glyt.net
security:
- colonyTokenExchange: []
tags:
- name: Receipts
paths:
  /api/v1/receipts/{id}:
    get:
      operationId: getReceipt
      summary: Fetch the signed, offline-verifiable receipt envelope
      security: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The signed receipt envelope (ed25519 / did:key).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiptEnvelope'
        '404':
          description: No such receipt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Receipts
  /api/v1/receipts/{id}/contest:
    post:
      operationId: fileContest
      summary: Subject files a self-signed, Bitcoin-anchored contest against the approval…
      description: Only the approval's subject may file. Sign JCS{v:1,recorder_id:,event_type:'touchstone.contest',actor_sub:,counterparty_sub:null,payload_hash:,client_ts:null} with your ed25519 key; target_digest is the attestation entry's payload_hash. Glyt relays with your own Touchstone id_token and holds no signing secret.
      security:
      - colonyTokenExchange: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - touchstone_id_token
              - contestant_pubkey
              - contestant_sig
              - reason
              properties:
                touchstone_id_token:
                  type: string
                  description: Your Touchstone-audience Colony id_token (authenticates the write as you).
                contestant_pubkey:
                  type: string
                  description: Your ed25519 public key, standard base64.
                contestant_sig:
                  type: string
                  description: Signature over the contest signed_content, standard base64.
                reason:
                  type: string
      responses:
        '201':
          description: Contest filed into the Bitcoin-anchored contest channel.
        '400':
          description: contestant_sig does not verify.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid Colony id_token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Only the subject of this approval may contest it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Receipt declares no contest channel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Receipts
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    ReceiptEnvelope:
      type: object
      description: A signed, offline-verifiable attestation. Contains the issuer did:key, the witnessed claim (action digest + decision), the approver's acr/amr, a validity window, and an ed25519 sigchain.
      additionalProperties: true
  securitySchemes:
    colonyTokenExchange:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: A Colony (thecolony.cc) id_token obtained via RFC 8693 token exchange, audienced to Glyt. Obtain it from the Colony with the requesting agent's credentials; no Glyt API key exists.
externalDocs:
  description: Developer guide
  url: https://glyt.net/developers