{
  "openapi": "3.1.1",
  "info": {
    "title": "DigiParser Agent API",
    "version": "1.0.0",
    "description": "Machine-readable entry point for DigiParser. Use the REST API for backend automation with an API key. Use the MCP server for an agent that acts for a signed-in user. The full REST reference is at https://digiparser.com/docs/api."
  },
  "servers": [
    { "url": "https://api.digiparser.com", "description": "REST API" }
  ],
  "externalDocs": {
    "description": "Full REST API reference",
    "url": "https://digiparser.com/docs/api"
  },
  "tags": [
    { "name": "Parsers", "description": "Discover the parsers available to an API key." },
    { "name": "Document processing", "description": "Upload documents for extraction." },
    { "name": "MCP", "description": "OAuth-protected tools for AI agents." }
  ],
  "paths": {
    "/api/v1/parsers": {
      "get": {
        "tags": ["Parsers"],
        "operationId": "listParsers",
        "summary": "List parsers available to an API key",
        "security": [{ "apiKeyAuth": [] }],
        "responses": {
          "200": { "description": "Parser list", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } },
          "401": { "$ref": "#/components/responses/ApiError" }
        }
      }
    },
    "/api/v1/process/files": {
      "post": {
        "tags": ["Document processing"],
        "operationId": "uploadFiles",
        "summary": "Upload files to a parser or classifier",
        "description": "Provide exactly one of parserId or classifierId.",
        "security": [{ "apiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "parserId": { "type": "string", "format": "uuid" },
                  "classifierId": { "type": "string", "format": "uuid" },
                  "file": { "type": "string", "format": "binary" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Documents accepted", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/ApiError" },
          "401": { "$ref": "#/components/responses/ApiError" },
          "403": { "$ref": "#/components/responses/ApiError" }
        }
      }
    },
    "/mcp": {
      "post": {
        "servers": [{ "url": "https://mcp.digiparser.com", "description": "Remote MCP server" }],
        "tags": ["MCP"],
        "operationId": "callMcpTool",
        "summary": "Call a DigiParser MCP tool",
        "description": "Use a current MCP client. Discover OAuth metadata at https://mcp.digiparser.com/.well-known/oauth-protected-resource/mcp. Request only the scopes needed for the tool call.",
        "security": [{ "mcpOAuth": ["mcp:read"] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } },
        "responses": {
          "200": { "description": "MCP JSON-RPC response", "content": { "application/json": { "schema": { "type": "object" } } } },
          "400": { "$ref": "#/components/responses/ApiError" },
          "401": { "$ref": "#/components/responses/ApiError" },
          "403": { "$ref": "#/components/responses/ApiError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "DigiParser REST API key. Send Bearer YOUR_API_KEY. API-key permissions are managed in Team Settings."
      },
      "mcpOAuth": {
        "type": "oauth2",
        "description": "OAuth 2.0 authorization code flow with PKCE for the remote MCP server.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://app.digiparser.com/api/oauth/mcp/authorize",
            "tokenUrl": "https://app.digiparser.com/api/oauth/mcp/token",
            "scopes": {
              "mcp:read": "View parsers, classifiers, documents, and configuration.",
              "mcp:parsers:write": "Create and manage parsers and classifiers.",
              "mcp:documents:write": "Upload, update, delete, and reprocess documents.",
              "mcp:fields:write": "Manage extraction fields and tables.",
              "mcp:folders:write": "Manage document folders.",
              "mcp:reviews:write": "Manage reviews and approvals.",
              "mcp:exports": "Export document data.",
              "mcp:webhooks:write": "Manage webhook endpoints."
            }
          }
        }
      }
    },
    "responses": {
      "ApiError": {
        "description": "Structured error response. Inspect code and resolution before retrying.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error", "code", "message", "resolution"],
        "properties": {
          "error": { "type": "boolean", "const": true },
          "code": { "type": "string", "example": "invalid_request" },
          "message": { "type": "string", "example": "Provide exactly one processing target." },
          "resolution": { "type": "string", "example": "Set parserId or classifierId, but not both, then retry." }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method", "id"],
        "properties": {
          "jsonrpc": { "const": "2.0" },
          "id": { "type": ["string", "integer"] },
          "method": { "type": "string" },
          "params": { "type": "object" }
        }
      }
    }
  }
}