docrocket-ai HTTPS JSON API

openapi: 3.2.0
info:
  title: DocRocket HTTPS JSON API
  description: 'DocRocket surfaces: (1) **HTTPS JSON API** at `api.docrocket.ai/v1` — POST a single JSON envelope with `action` plus optional `account_id`, `user_id`, and a `body` object for action-specific fields. Use an Auth0 access token or DocRocket API key JWT in `Authorization: Bearer`. (2) **MCP-aligned HTTP paths** on the MCP gateway for high-level document flows. (3) **Direct Lambda invoke** with the same envelope shape for batch/tool integrations.'
  version: 1.0.0
  contact:
    email: hello@docrocket.ai
    url: https://docrocket.ai
  x-mcp-endpoint: https://mcp.docrocket.ai/v1/mcp-tools/docrocket-control/mcp
servers:
- url: https://api.docrocket.ai/v1
  description: Production HTTPS API (Auth0 or API key JWT)
- url: https://mcp.docrocket.ai/v1/mcp-tools/docrocket-control
  description: DocRocket MCP HTTP gateway (OAuth / MCP client flows)
security:
- oauth2: []
tags:
- name: HTTPS JSON API
paths:
  /:
    post:
      tags:
      - HTTPS JSON API
      operationId: http_invoke_action
      summary: Invoke a tool action (customer route)
      servers:
      - url: https://api.docrocket.ai/v1
        description: Production HTTPS API
      description: 'POST the JSON **envelope** to invoke any customer-scoped action (`brands.*`, `content.*`, `design.*`, `render.run`, `billing.*`, `users.*`, `api_keys.*`, `inspector.*`, …). Send `Authorization: Bearer` with an Auth0 access token (same audience as the DocRocket app) or an API key JWT.


        Action-specific parameters go in the `body` object (merged server-side with the envelope). Underscore tool names from direct invoke (e.g. `content_list_docs`) are accepted as aliases for dotted actions.


        **Do not** send `admin.*` here — use `POST /admin` with a Cognito admin access token.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              properties:
                action:
                  type: string
                  description: Dotted action name, e.g. `content.list_docs`, `render.run`, `brands.put`.
                  example: content.list_docs
                account_id:
                  description: Account scope (string or integer); required for most writes and multi-tenant reads.
                  oneOf:
                  - type: string
                  - type: integer
                user_id:
                  type: string
                  description: End-user id (email-shaped for interactive auth). Required for several write paths.
                request_id:
                  type: string
                  description: Optional idempotency / tracing id echoed in logs.
                roles:
                  type: array
                  items:
                    type: string
                  description: Optional role hints such as `brand_admin`, `brand_editor`, `viewer` for tighter brand ACLs.
                body:
                  type: object
                  additionalProperties: true
                  description: Action-specific payload (e.g. `doc_id` for content reads, `markdown` + `formats` for `render.run`). Defaults to `{}`.
            examples:
              listDocs:
                summary: List documents
                value:
                  action: content.list_docs
                  account_id: '426'
                  user_id: you@example.com
                  body: {}
              renderRun:
                summary: Render markdown
                value:
                  action: render.run
                  account_id: '426'
                  user_id: you@example.com
                  body:
                    markdown: '# Title


                      Hello from the API.'
                    formats:
                    - html
      responses:
        '200':
          description: 'Success — JSON `{ "success": true, "data": … }`'
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                properties:
                  success:
                    const: true
                  data:
                    description: Action result payload
        '400':
          description: 'Validation or bad request — `{ "success": false, "error": { "code", "message", "details"? } }`'
        '401':
          description: Missing or invalid bearer token
        '403':
          description: Forbidden for this principal or action
        '404':
          description: Not found
        '409':
          description: Conflict (e.g. document version mismatch)
        '500':
          description: Server error
  /admin:
    post:
      tags:
      - HTTPS JSON API
      operationId: http_invoke_admin_action
      summary: Invoke an admin action (Cognito)
      servers:
      - url: https://api.docrocket.ai/v1
        description: Production HTTPS API
      description: Same envelope as `POST /`, but requires a **Cognito** admin access token (DocRocket admin SPA). Use for `admin.*` and `admin.master.*` operations. Customer actions that are not admin should use `POST /` with Auth0.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              properties:
                action:
                  type: string
                  example: admin.brands.list
                account_id:
                  type: string
                user_id:
                  type: string
                request_id:
                  type: string
                body:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    const: true
                  data: {}
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Auth0 access token (DocRocket SPA audience) or DocRocket-issued API key JWT.
    oauth2:
      type: oauth2
      description: OAuth 2.0 via DocRocket account. No API keys needed.
      flows:
        authorizationCode:
          authorizationUrl: https://app.docrocket.ai/oauth/authorize
          tokenUrl: https://app.docrocket.ai/oauth/token
          scopes:
            documents:write: Generate documents
            documents:read: Read documents
            brands:write: Create and update brands
            brands:read: Read brands
            templates:read: Read templates