ApplyToVolunteer Conversions API

openapi: 3.2.0
info:
  title: Apply2Volunteer Conversions API
  version: 1.0.0
  description: 'Convert volunteer PDFs into progressive online forms. Organization owners and admins create API keys in the dashboard. Send a key as Authorization: Bearer a2v_... The token starts with a2v_. This API does not implement OAuth. Public submit and anonymous grade or convert do not accept the key in place of a Turnstile token. Keyless agents use /mcp and POST /a2a for anonymous grade and preview.'
  license:
    name: Proprietary
    url: https://applytovolunteer.com/terms
servers:
- url: https://applytovolunteer.com
security:
- orgApiKey: []
tags:
- name: Conversions
paths:
  /api/v1/conversions:
    post:
      operationId: createConversion
      summary: Start a PDF or URL conversion
      description: Ingest a PDF/URL (auth, rate-limited). Requires a browser session or an org API key with forms:write. The key's organization must match orgId when orgId is set.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Organization id. An API key uses its own organization when this is omitted, and must match it when it is set. A browser session uses the caller's first organization when this is omitted.
        required: false
        description: Organization id. An API key uses its own organization when this is omitted, and must match it when it is set. A browser session uses the caller's first organization when this is omitted.
        name: orgId
        in: query
      requestBody:
        required: true
        description: Send JSON { url } or multipart/form-data with file. One of the two is required.
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: http(s) URL of a PDF, Word file, or HTML page. The server fetches it. Maximum 15 MB.
              required:
              - url
              description: JSON alternative to multipart file upload.
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: PDF, Word (.docx), or image. Maximum 15 MB.
                  format: binary
              required:
              - file
              description: Multipart alternative to a JSON url.
      responses:
        '202':
          description: Conversion queued. Poll GET /api/v1/conversions/{id}.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Conversion id.
                required:
                - id
        '400':
          description: The body, query, or input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: No signed-in session and no live org API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: The API key is missing a required scope, or the action is not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too many requests from this network or organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Conversions
  /api/v1/conversions/{id}:
    get:
      operationId: getConversion
      summary: Poll a conversion
      description: Poll a conversion. Requires a browser session or an org API key with forms:read. A missing or wrong key is 404, not 401.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Conversion id.
        required: true
        description: Conversion id.
        name: id
        in: path
      responses:
        '200':
          description: Poll a conversion
        '404':
          description: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Conversions
components:
  schemas:
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: Short error code or message.
        message:
          type: string
          description: Human-readable detail when the handler sends one.
        fields:
          type: object
          additionalProperties:
            type: string
          description: Field-level validation messages.
        retryable:
          type: boolean
          description: Set on some public submit conflicts.
      required:
      - error
  securitySchemes:
    orgApiKey:
      type: http
      scheme: bearer
      bearerFormat: a2v API key
      description: Organization API key. REST reads Authorization and accepts only the exact prefix "Bearer " (capital B, one space) followed by a token that starts with a2v_. Put the a2v_ token in the bearer credential. Do not include the word Bearer in the token. Owners and admins create keys at /app/settings/api-keys. The secret is shown once. Revoked keys are rejected. This API does not implement OAuth. Scopes are forms:read, forms:write, applications:read, and applications:write. forms:write does not include forms:read. A new key defaults to forms:read and forms:write. applications:read and applications:write are opt-in. A browser session cookie is also accepted on organization routes. Agents send the bearer key.