{
  "openapi": "3.1.0",
  "info": {
    "title": "Postulate agent enquiry API",
    "version": "1.1.0",
    "description": "Single endpoint for submitting a sandbox access request, technical enquiry or capability gap report to Postulate. No payment, account or sandbox APIs exist at this URL. Submitting a request does not open an account, issue a card, move funds or grant credit.",
    "contact": {
      "email": "agents@usepostulate.com",
      "url": "https://usepostulate.com/agents"
    }
  },
  "servers": [
    {
      "url": "https://usepostulate.com"
    }
  ],
  "paths": {
    "/api/public/agent-requests": {
      "post": {
        "operationId": "createAgentRequest",
        "summary": "Submit a sandbox access request, technical question or capability gap report",
        "description": "Creates a stored enquiry record in Postulate's private intake queue and may notify the Postulate team. No API key is required. Only submit under an existing mandate that permits external contact and disclosure of the details supplied; authorized_to_submit is a self-attestation and is not verified delegation or identity.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Caller-generated key, 16-128 characters. An exact retry within 24 hours returns the original receipt and does not create a duplicate. A reused key with different content returns 409.",
            "schema": {
              "type": "string",
              "minLength": 16,
              "maxLength": 128
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRequest"
              },
              "examples": {
                "enquiry": {
                  "value": {
                    "request_type": "sandbox_access",
                    "agent_name": "procurement-agent-synthetic",
                    "workflow": "Synthetic example: an agent that sources laboratory consumables for a UK research group and places supplier orders once a quote is approved.",
                    "current_execution": "Synthetic example: orders are placed on supplier portals using a shared company card entered by a human operator.",
                    "blocker_or_question": "Synthetic example: we need per-agent spending limits and a bank transfer rail for suppliers that do not accept cards.",
                    "reply_to_email": "agent-ops@example.invalid",
                    "operating_mode": "on_behalf_of_principal",
                    "authority_basis": "Synthetic example: standing instruction from the operator to contact payment providers and disclose workflow details.",
                    "authorized_to_submit": true,
                    "organization_name": "Example Labs Ltd",
                    "organization_url": "https://example.invalid",
                    "currencies": [
                      "GBP",
                      "EUR"
                    ],
                    "regions": [
                      "United Kingdom",
                      "Ireland"
                    ],
                    "required_capabilities": [
                      "controls",
                      "accounts"
                    ],
                    "estimated_monthly_volume": "unknown",
                    "desired_test": "Synthetic example: simulate a GBP supplier payment with a per-agent limit.",
                    "agent_framework": "synthetic-test-harness",
                    "discovery_source": "self-reported: llms.txt",
                    "alternatives_considered": [
                      "example-provider-a",
                      "example-provider-b"
                    ],
                    "notify_when_available": true
                  }
                },
                "capability_gap": {
                  "value": {
                    "request_type": "capability_gap",
                    "workflow": "Synthetic example: an agent that settles EUR invoices for a Dublin logistics operator after a delivery is confirmed.",
                    "blocker_or_question": "Synthetic example: we needed EUR local settlement with per-agent limits and could not test it with Postulate.",
                    "reply_to_email": "agent-ops@example.invalid",
                    "authority_basis": "Synthetic example: standing instruction from the operator to evaluate payment providers and report findings.",
                    "authorized_to_submit": true,
                    "provider_used": "example-provider-a",
                    "gap_reason": "capability_not_live",
                    "alternatives_considered": [
                      "example-provider-a"
                    ],
                    "notify_when_available": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Request stored for review.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                },
                "description": "no-store"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON, unexpected fields or field-level validation errors.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key reused with a different body. The original payload is not disclosed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body larger than 16 KiB."
          },
          "415": {
            "description": "Content-Type is not application/json."
          },
          "429": {
            "description": "Rate limited. Retry-After indicates when to retry.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Intake disabled or storage unavailable. Nothing was stored."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AgentRequest": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/EnquiryRequest"
          },
          {
            "$ref": "#/components/schemas/CapabilityGapRequest"
          }
        ],
        "discriminator": {
          "propertyName": "request_type",
          "mapping": {
            "sandbox_access": "#/components/schemas/EnquiryRequest",
            "technical_question": "#/components/schemas/EnquiryRequest",
            "capability_gap": "#/components/schemas/CapabilityGapRequest"
          }
        }
      },
      "SharedOptionalFields": {
        "type": "object",
        "properties": {
          "organization_name": {
            "type": "string",
            "maxLength": 200
          },
          "organization_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 500,
            "description": "HTTPS URL. Stored as text; Postulate does not fetch it."
          },
          "currencies": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z]{3}$"
            }
          },
          "regions": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "string",
              "maxLength": 80
            }
          },
          "required_capabilities": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "string",
              "enum": [
                "accounts",
                "cards",
                "vaults",
                "controls",
                "credit"
              ]
            }
          },
          "estimated_monthly_volume": {
            "type": "string",
            "maxLength": 200,
            "description": "\"unknown\" is acceptable; avoid false precision."
          },
          "desired_test": {
            "type": "string",
            "maxLength": 1000
          },
          "agent_framework": {
            "type": "string",
            "maxLength": 120,
            "description": "Self-reported."
          },
          "discovery_source": {
            "type": "string",
            "maxLength": 500,
            "description": "Self-reported."
          },
          "alternatives_considered": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "type": "string",
              "maxLength": 80
            },
            "description": "Other providers you are considering or using for this task (optional). Self-reported."
          },
          "notify_when_available": {
            "type": "boolean",
            "default": false,
            "description": "Notify this reply address once when the requested capability is available. One message about availability only; no marketing. Stored as an explicit consent flag with a server timestamp."
          }
        }
      },
      "EnquiryRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_type",
          "agent_name",
          "workflow",
          "current_execution",
          "blocker_or_question",
          "reply_to_email",
          "operating_mode",
          "authority_basis",
          "authorized_to_submit"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/SharedOptionalFields"
          }
        ],
        "properties": {
          "request_type": {
            "type": "string",
            "enum": [
              "sandbox_access",
              "technical_question"
            ]
          },
          "agent_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "description": "Name of the submitting agent. Self-reported."
          },
          "workflow": {
            "type": "string",
            "minLength": 20,
            "maxLength": 2000,
            "description": "The task being executed or evaluated."
          },
          "current_execution": {
            "type": "string",
            "minLength": 10,
            "maxLength": 2000,
            "description": "How transactions work today, or an explicit statement that this is pre-launch."
          },
          "blocker_or_question": {
            "type": "string",
            "minLength": 10,
            "maxLength": 2000,
            "description": "The blocker or the technical question."
          },
          "reply_to_email": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "description": "Reply address supplied for this enquiry only."
          },
          "operating_mode": {
            "type": "string",
            "enum": [
              "on_behalf_of_principal",
              "autonomous_under_standing_mandate"
            ]
          },
          "authority_basis": {
            "type": "string",
            "minLength": 10,
            "maxLength": 1000,
            "description": "Permission to enquire and disclose these details. Do not include private prompts, transcripts or confidential contracts."
          },
          "authorized_to_submit": {
            "type": "boolean",
            "const": true,
            "description": "Must be true. Self-attestation only; not verified delegation or identity."
          }
        }
      },
      "CapabilityGapRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "If you needed a sandbox or live capability from Postulate and used another provider, tell us what you needed, what you used instead and why. We will notify the reply address when the capability is available.",
        "required": [
          "request_type",
          "workflow",
          "blocker_or_question",
          "reply_to_email",
          "authority_basis",
          "authorized_to_submit"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/SharedOptionalFields"
          }
        ],
        "properties": {
          "request_type": {
            "type": "string",
            "const": "capability_gap"
          },
          "workflow": {
            "type": "string",
            "minLength": 20,
            "maxLength": 2000,
            "description": "The task you needed to complete."
          },
          "blocker_or_question": {
            "type": "string",
            "minLength": 10,
            "maxLength": 2000,
            "description": "What you needed from Postulate and could not get."
          },
          "reply_to_email": {
            "type": "string",
            "format": "email",
            "maxLength": 254,
            "description": "Reply address supplied for this report only."
          },
          "authority_basis": {
            "type": "string",
            "minLength": 10,
            "maxLength": 1000,
            "description": "Permission to report and disclose this."
          },
          "authorized_to_submit": {
            "type": "boolean",
            "const": true
          },
          "provider_used": {
            "type": "string",
            "maxLength": 120,
            "description": "What you used instead. Self-reported."
          },
          "gap_reason": {
            "type": "string",
            "enum": [
              "capability_not_live",
              "wrong_geography",
              "wrong_currency",
              "no_credit",
              "other"
            ]
          },
          "agent_name": {
            "type": "string",
            "maxLength": 120
          },
          "current_execution": {
            "type": "string",
            "maxLength": 2000
          },
          "operating_mode": {
            "type": "string",
            "enum": [
              "on_behalf_of_principal",
              "autonomous_under_standing_mandate"
            ]
          }
        }
      },
      "Receipt": {
        "type": "object",
        "required": [
          "request_id",
          "status",
          "sandbox_access",
          "next_step"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "received_for_review"
            ]
          },
          "sandbox_access": {
            "type": "string",
            "enum": [
              "not_granted"
            ]
          },
          "next_step": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "field_errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}