agendaforge-app Connection API

openapi: 3.2.0
info:
  title: AgendaForge Public REST Connection API
  version: 1.0.0
  summary: 'Server-to-server REST API for the AgendaForge event-management platform: webhooks (REST Hooks), sample records, cursor-paginated list endpoints, create actions and batch create for contacts, sessions, and sponsors, and async contact and ticket imports with pollable jobs.'
  description: 'The HTTP API that powers the AgendaForge Zapier, Make.com, and n8n integrations, and any custom server-to-server integration.


    Every request is authenticated with an organization API key (created in Settings > API Tokens; keys begin with afk_live_ and are shown once). Keys carry named scopes chosen at creation: public_api (this API, on by default), mcp:read and mcp:write (the AgendaForge MCP server for AI clients), and tickets:import (ticket imports, never on by default). Every endpoint here requires the public_api scope, except POST /api/v1/imports/tickets, which requires tickets:import; requests with a key that lacks the required scope receive 403 FORBIDDEN.


    All requests and responses are JSON. Every error, 4xx and 5xx alike, is JSON of the shape { "error": { "code": "...", "message": "..." } } with a machine-readable code and a human-readable resolution hint. Unknown paths under /api/v1 return 404 NOT_FOUND with the list of valid endpoints.


    Pagination: list endpoints (GET /contacts, GET /sessions, GET /sponsors) are cursor-based. Request a page with ?limit= (1-100, default 25), then follow nextCursor via ?cursor= until hasMore is false. Cursors are opaque continuation tokens; never construct one.


    Long-running work: POST /api/v1/imports/contacts answers 202 Accepted with a job id and a statusUrl (also in the Location header); poll GET /api/v1/jobs/{id} until status reaches completed or failed. For up to 100 items in one synchronous call, use POST /api/v1/contacts/batch instead. POST /api/v1/imports/tickets finishes up to 100 tickets inside the request (200, job already completed) and queues 101 to 1,000 tickets (202, poll the same way).


    Rate limits: 120 requests per minute per API key (fixed window), and 30 requests per minute per IP for unauthenticated requests. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds until the window resets), and RateLimit-Policy headers so clients can self-throttle; exceeding the window returns 429 RATE_LIMITED with a Retry-After header.


    Versioning and deprecation: the API is versioned in the URL path (/api/v1). Additive changes (new endpoints, new optional fields, new webhook events) happen within a version and are never breaking; breaking changes ship only as a new version path. If an endpoint or version is ever deprecated it will be announced in the changelog at least 180 days before removal and signaled with Deprecation and Sunset headers on affected responses. Nothing is deprecated today.


    Human-readable reference: https://agendaforge.app/docs/api. Developer portal: https://agendaforge.app/developers. Site content for agents: https://agendaforge.app/llms.txt.'
  contact:
    name: AgendaForge support
    email: hello@agendaforge.app
    url: https://agendaforge.app/docs/api
  termsOfService: https://agendaforge.app/terms
servers:
- url: https://api.agendaforge.app
  description: Production
security:
- bearerApiKey:
  - public_api
- headerApiKey:
  - public_api
tags:
- name: Connection
  description: Validate a key and identify the organization it is scoped to.
paths:
  /api/v1/me:
    get:
      security:
      - bearerApiKey:
        - public_api
      - headerApiKey:
        - public_api
      x-required-scopes:
      - public_api
      operationId: getMe
      tags:
      - Connection
      summary: Validate the API key and return its organization
      description: Auth test / connection label. Returns the organization the key is scoped to. Use this to verify a key before configuring an integration.
      responses:
        '200':
          description: The organization the key is scoped to.
          content:
            application/json:
              schema:
                type: object
                required:
                - orgId
                - orgName
                properties:
                  orgId:
                    type: string
                    description: Opaque organization id.
                  orgName:
                    type: string
                    description: Display name of the organization.
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/UnexpectedError'
components:
  responses:
    UnexpectedError:
      description: Any other failure, including 404 NOT_FOUND for an unknown path and transient 5xx errors. Always the same JSON error contract.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL
              message: Unexpected server error. Retry with exponential backoff; if it persists, contact hello@agendaforge.app.
    NotFound:
      description: No such endpoint under /api/v1. The message lists the valid endpoints.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: No such endpoint. See https://agendaforge.app/openapi.json for the API surface.
    InternalError:
      description: An unexpected server failure. The body still follows the JSON error contract; retry with exponential backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL
              message: Unexpected server error. Retry with exponential backoff; if it persists, contact hello@agendaforge.app.
    Unauthenticated:
      description: The API key is missing, malformed, invalid, expired, or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHENTICATED
              message: 'Missing API key. Send ''Authorization: Bearer <key>''.'
    Forbidden:
      description: The API key is valid but does not include the public_api scope. Create a key with the public_api scope in Settings > API Tokens.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: FORBIDDEN
              message: This API key does not include the "public_api" scope. Create a key with the public_api scope in Settings > API Tokens.
    RateLimited:
      description: The fixed window for this API key (120 requests per minute) or IP (30 per minute, unauthenticated) is exhausted. Wait Retry-After seconds and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RATE_LIMITED
              message: Rate limit exceeded. Retry after the number of seconds in the Retry-After header.
      headers:
        Retry-After:
          description: Seconds to wait before retrying (RFC 6585).
          schema:
            type: string
        RateLimit-Limit:
          description: Requests allowed per window. Sent on every /api/v1 response, not only 429s.
          schema:
            type: string
        RateLimit-Remaining:
          description: Requests left in the current window.
          schema:
            type: string
        RateLimit-Reset:
          description: Seconds until the current window resets.
          schema:
            type: string
        RateLimit-Policy:
          description: The policy as "<limit>;w=<window seconds>", e.g. "120;w=60".
          schema:
            type: string
  schemas:
    Error:
      type: object
      required:
      - error
      description: Every non-2xx response carries this JSON shape. The code is machine-readable; the message is a human-readable resolution hint.
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - UNAUTHENTICATED
              - FORBIDDEN
              - VALIDATION_ERROR
              - PAYMENT_REQUIRED
              - NOT_FOUND
              - RATE_LIMITED
              - CONFLICT
              - INTERNAL
            message:
              type: string
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: afk_live_ organization API key
      description: 'Organization API key sent as "Authorization: Bearer afk_live_...". Keys are created in Settings > API Tokens with named scopes (see x-api-key-scopes): public_api grants this REST API; mcp:read and mcp:write grant the AgendaForge MCP server; tickets:import grants ticket imports. Every endpoint here requires the public_api scope except POST /api/v1/imports/tickets, which requires tickets:import.'
      x-scopes:
      - public_api
      - mcp:read
      - mcp:write
      - tickets:import
    headerApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: The same afk_live_ organization API key sent as an X-API-Key header instead of a Bearer token. Identical scope semantics to bearerApiKey.
      x-scopes:
      - public_api
      - mcp:read
      - mcp:write
      - tickets:import
externalDocs:
  description: AgendaForge API reference (human-readable)
  url: https://agendaforge.app/docs/api
x-api-key-scopes:
- name: public_api
  description: Grants the public REST API v1 (this specification). On by default when a key is created. Required by every endpoint here except POST /api/v1/imports/tickets; a key without it receives 403 FORBIDDEN.
- name: mcp:read
  description: Grants read tools on the AgendaForge MCP server for AI clients (events, sessions, contacts, forms). MCP keys act as the admin who created them and are re-checked against live membership on every call.
- name: mcp:write
  description: 'Grants write tools on the AgendaForge MCP server. Every write is approval-gated: the AI proposes, a person approves.'
- name: tickets:import
  description: Grants POST /api/v1/imports/tickets and polling its jobs at GET /api/v1/jobs/{id}. Labeled "Import tickets" in Settings > API Tokens. Never on by default and never implied by another scope; it does not grant the other endpoints here.