WritersLogic Verifiable AI Agent Hub Publishing API

openapi: 3.2.0
info:
  title: WritersProof Publishing API
  version: 1.0.0
  description: Certificate Authority and verification API for the Proof-of-Effort protocol. Certify, verify, and prove human authorship.
  contact:
    name: WritersLogic LLC
    url: https://writersproof.com
  license:
    name: SSPL-1.0
    url: https://www.mongodb.com/licensing/server-side-public-license
servers:
- url: https://api.writersproof.com
  description: Production
- url: https://api.writerslogic.com
  description: Legacy
tags:
- name: Publishing
  description: Register evidence for public verification, with optional notarization
paths:
  /v1/publish:
    post:
      tags:
      - Publishing
      operationId: publishEvidence
      summary: Publish evidence for public verification
      description: 'Register an evidence hash so /verify can resolve it. On a paid tier, supplying `evidenceB64` also verifies the packet, stores it, and CA-counter-signs it. Idempotent per (user, evidenceHash): a repeat publish returns 200 with the existing record.'
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
      responses:
        '200':
          description: Already published — the existing record, unchanged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishResponse'
        '201':
          description: Evidence published
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishResponse'
        '400':
          description: Request validation failed (no `code`), or the uploaded packet was rejected (`code` set — see PublishError).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The publish signature did not verify against the author's enrolled hardware key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Verification, storage, or insert failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishError'
        '503':
          description: Notarization CA key not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PublishError:
      type: object
      description: The `error` string is fixed guidance safe to show a user; verifier diagnostics never reach it. Branch on `code`, which is absent on plain request-validation failures.
      properties:
        error:
          type: string
        requestId:
          type: string
        code:
          type: string
          enum:
          - invalid_evidence_encoding
          - malformed_evidence
          - unsigned_evidence
          - invalid_evidence_signature
          - invalid_checkpoint_count
          - invalid_checkpoint_chain
          - missing_recording_proof
          - invalid_checkpoint_timestamps
          - unsupported_evidence_profile
          - invalid_evidence
          - invalid_document_hash
          - evidence_document_mismatch
          - evidence_verification_failed
      required:
      - error
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    PublishRequest:
      type: object
      properties:
        evidenceHash:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: SHA-256 of the document content, hex. Must equal the packet's own documentRef hash.
        authorDid:
          type: string
          maxLength: 256
        signature:
          type: string
          pattern: ^[0-9a-f]{128}$
          description: Ed25519 over `b"witnessd-publish-v1" || content_hash` (32 raw bytes). Checked only when the author has an enrolled hardware key.
        attestation:
          type: string
        checkpointCount:
          type: integer
          minimum: 0
        documentName:
          type: string
          maxLength: 512
        aiDeclaration:
          type: string
        evidenceB64:
          type: string
          description: The .cpoe packet, base64. Paid tiers only; supplying it upgrades the publish to a full notarization.
      required:
      - evidenceHash
      - authorDid
      - signature
    PublishResponse:
      type: object
      properties:
        recordId:
          type: string
          format: uuid
        canonicalUrl:
          type: string
          format: uri
        publishedAt:
          type: integer
          description: Unix seconds
      required:
      - recordId
      - canonicalUrl
      - publishedAt
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase JWT token
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key with wp_sk_ prefix