XBRL2JSON API v1

1. Authentication

All API requests require an API key passed in the X-API-KEY HTTP header. You can create and manage your keys on the API Keys page.

curl -H "X-API-KEY: your_api_key_here" \
     https://xbrl2json.co.uk/api/v1/me/quota-summary

2. Base URL & Versioning

All endpoints are prefixed with:

https://xbrl2json.co.uk/api/v1/

The version is embedded in the URL path. A custom X-Api-Version response header is included in every response for programmatic version detection.

3. Response Format

All successful responses are wrapped in a standard JSON envelope:

Single-item response

{
  "data": { ... }
}

Paginated response

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "pageSize": 25,
    "totalCount": 142,
    "totalPages": 6,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

4. Error Handling

Error responses use a consistent envelope with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Job not found."
  }
}

5. Rate Limits

The API enforces burst-rate limits to protect service stability. These are in addition to your monthly quota.

When rate-limited, you'll receive a 429 response with a Retry-After header indicating how many seconds to wait before retrying.

6. Quick Start

Submit an XBRL file, poll for completion, then fetch the results — in three steps:

Step 1 — Submit a file

curl -X POST https://xbrl2json.co.uk/api/v1/jobs \
     -H "X-API-KEY: your_api_key_here" \
     -F "file=@report.xbrl"

# Response (202 Accepted):
# {
#   "data": {
#     "jobId": "01J5KXYZ...",
#     "status": "Pending",
#     "statusUrl": "https://xbrl2json.co.uk/api/v1/jobs/01J5KXYZ..."
#   }
# }

Step 2 — Poll for status

curl https://xbrl2json.co.uk/api/v1/jobs/01J5KXYZ... \
     -H "X-API-KEY: your_api_key_here"

# Poll every 1-2 seconds until "isTerminal": true
# {
#   "data": {
#     "jobId": "01J5KXYZ...",
#     "status": "Succeeded",
#     "isTerminal": true,
#     "factsCount": 847,
#     "resultUrl": "https://xbrl2json.co.uk/api/v1/parse-results/01J5KXYZ..."
#   }
# }

Step 3 — Fetch results & facts

# Get parse result detail
curl https://xbrl2json.co.uk/api/v1/parse-results/01J5KXYZ... \
     -H "X-API-KEY: your_api_key_here"

# Get extracted facts (paginated)
curl "https://xbrl2json.co.uk/api/v1/parse-results/01J5KXYZ.../facts?page=1&pageSize=50" \
     -H "X-API-KEY: your_api_key_here"

7. Endpoints

curl -X POST https://xbrl2json.co.uk/api/v1/jobs \
     -H "X-API-KEY: your_api_key_here" \
     -F "file=@report.xbrl" \
     -F "group=12345678" \
     -F "webhookUrl=https://example.com/webhook"

curl https://xbrl2json.co.uk/api/v1/jobs/01J5KXYZ... \
     -H "X-API-KEY: your_api_key_here"

curl -X POST https://xbrl2json.co.uk/api/v1/jobs/01J5KXYZ.../cancel \
     -H "X-API-KEY: your_api_key_here"

curl https://xbrl2json.co.uk/api/v1/parse-results/01J5KXYZ... \
     -H "X-API-KEY: your_api_key_here"

curl "https://xbrl2json.co.uk/api/v1/parse-results/01J5KXYZ.../facts?concept=Revenue&numericOnly=true&page=1&pageSize=50" \
     -H "X-API-KEY: your_api_key_here"

curl "https://xbrl2json.co.uk/api/v1/facts-by-filename?fileName=report.xbrl" \
     -H "X-API-KEY: your_api_key_here"

# 200 OK
# X-Document-PublicId: 01J5KXYZ...
# X-ParseJob-PublicId: 01J5KABC...
# X-Response-Source: StoredJson
# Content-Type: application/json
#
# { ... raw parser JSON output ... }

curl "https://xbrl2json.co.uk/api/v1/facts-by-filename?fileName=missing.xbrl" \
     -H "X-API-KEY: your_api_key_here"

# 404 Not Found
# {
#   "error": {
#     "code": "DOCUMENT_NOT_FOUND",
#     "message": "No uploaded document with that file name was found."
#   }
# }

curl "https://xbrl2json.co.uk/api/v1/conversions?succeededOnly=true&page=1&pageSize=10" \
     -H "X-API-KEY: your_api_key_here"

curl https://xbrl2json.co.uk/api/v1/me/quota-summary \
     -H "X-API-KEY: your_api_key_here"

8. Webhooks

Instead of polling, you can supply a webhookUrl when submitting a job. When the job reaches a terminal state, the API will send a signed POST request to your URL with the job status payload.

9. Idempotency

To prevent duplicate job submissions (e.g. due to network retries), include an idempotencyKey form field with your submit request. If a job with the same key already exists for your account, the API returns 409 Conflict with the existing job's identifier.

curl -X POST https://xbrl2json.co.uk/api/v1/jobs \
     -H "X-API-KEY: your_api_key_here" \
     -F "file=@report.xbrl" \
     -F "idempotencyKey=my-unique-key-12345"

10. MCP (Model Context Protocol)

Overview

XBRL2JSON also acts as an MCP server, allowing AI assistants (such as Claude, GitHub Copilot, Cursor, and other MCP-compatible clients) to interact with your XBRL data through natural-language tool calls.

The MCP server exposes the same core functionality as the REST API — submitting XBRL files for processing, checking job status, retrieving parse results, exploring extracted facts, listing conversions, and viewing quota usage — but through the Model Context Protocol standard, using the Streamable HTTP transport.

Connecting

The MCP endpoint is available at:

https://xbrl2json.co.uk/mcp

Authentication uses the same X-API-KEY header as the REST API. Your MCP client must send this header with every request to the MCP endpoint.

Typical workflow. Ask your assistant in natural language and it calls the tools for you. A submission flows submit_job → poll get_job_status until isTerminal is true → get_parse_result for the summary and get_facts to page through extracted facts. Use list_conversions to find earlier jobs and get_quota_summary to check usage.

Every tool except submit_job is read-only, all tools return structured output (with an output schema clients can validate against), and failures are reported as MCP tool errors so a client can tell a failure apart from a successful result.

Available Tools

The MCP server exposes the following tools that AI clients can call:

Resources

As well as tools, the server exposes a job's output as MCP resources — addressable, attachable content under the xbrl2json:// URI scheme. An assistant can attach these directly as context instead of issuing a tool call. Resources are scoped to your API key, and each read counts against your monthly API quota the same as a tool call.

Prompts

The server also offers reusable prompts — ready-made templates for common analyses that your client can surface (often as slash-commands). Each expands into an instruction that drives the tools and resources above; the data work happens when the assistant runs them.

Client Configuration

Below are example configurations for popular MCP clients.

Claude Code (CLI)

Register the server with a single command:

claude mcp add --transport http xbrl2json https://xbrl2json.co.uk/mcp \
  --header "X-API-KEY: your_api_key_here"

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "xbrl2json": {
      "type": "streamable-http",
      "url": "https://xbrl2json.co.uk/mcp",
      "headers": {
        "X-API-KEY": "your_api_key_here"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add the following to your .vscode/mcp.json file:

{
  "servers": {
    "xbrl2json": {
      "type": "http",
      "url": "https://xbrl2json.co.uk/mcp",
      "headers": {
        "X-API-KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

Add the following to your .cursor/mcp.json file:

{
  "mcpServers": {
    "xbrl2json": {
      "url": "https://xbrl2json.co.uk/mcp",
      "headers": {
        "X-API-KEY": "your_api_key_here"
      }
    }
  }
}

For interactive testing and full schema details, visit the Swagger UI. Need help? Contact us.