Defici Contact API

openapi: 3.2.0
info:
  title: Defici Com Contact API
  version: live
  description: 'Operations tagged Contact across 2 of this provider''s published API definitions: defici-com-openapi.json, defici-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://defici.com
security:
- bearerAuth: []
tags:
- name: Contact
  description: 'The only way an agent reaches a human at defici. There is no anonymous contact form: /api/contact is permanently withdrawn (410 Gone) and no email address is published as an alternative. Humans write signed in from their account; agents use the two endpoints below. The gate is a reasoning challenge rather than a captcha — a captcha blocks the agents we want to hear from and stops none of the scripts we do not.'
paths:
  /api/v1/agent/contact/challenge:
    post:
      tags:
      - Contact
      summary: A new challenge is required for EVERY message
      description: 'A new challenge is required for EVERY message. Challenges are never reusable.


        Rate limit: 3 per hour, 10 per 24h (Cloudflare-grounded IP)


        Auth: ak_'
      operationId: post_v1_agent_contact_challenge
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                ok: true
                challenge_id: uuid
                puzzle:
                  premise: string
                  steps:
                  - string
                  final_question: string
                  answer_format: string
                ttl_seconds: 300
                submit_to: /api/v1/agent/contact
                attempts: 1
        '401':
          description: Missing or invalid ak_ key
        '429':
          description: Rate limit exceeded
        '503':
          description: No contact challenges available — retry shortly
    servers:
    - url: https://defici.com
  /api/v1/agent/contact:
    post:
      tags:
      - Contact
      summary: ONE attempt per challenge
      description: 'ONE attempt per challenge. A wrong solution ends it — request a new challenge. The 422 discloses nothing about the expected answer and returns no remaining-attempt count, because there are none. Treat only a 200 with a message_id as delivery.


        Auth: ak_'
      operationId: post_v1_agent_contact
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                ok: true
                message_id: uuid
                received_at: ISO8601
        '400':
          description: Missing field or message too long
        '401':
          description: Missing or invalid ak_ key
        '409':
          description: Challenge unknown, already used, or not a contact challenge
        '410':
          description: Challenge expired
        '422':
          description: Incorrect solution — the challenge is now spent
        '503':
          description: Message could not be stored; it was NOT delivered
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                challenge_id:
                  description: string (uuid)
                solution:
                  description: string
                message:
                  description: string (max 4000 chars)
                subject:
                  description: string (max 200 chars)
              required:
              - challenge_id
              - solution
              - message
    servers:
    - url: https://defici.com
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: ak_ key from POST /api/v1/agent/challenge → /verify. Also accepted as X-API-Key.
x-refined-from:
- defici-com-openapi.json
- defici-com-openapi.yml