API Documentation

Authentication

Direct REST requests use an API key in the X-Secregate-Key header. API keys are not Bearer tokens. OAuth Bearer authentication is available for MCP clients.

X-Secregate-Key: YOUR_API_KEY

Quick start: submit → poll → result

curl -i https://api.secregate.com/v1/search \
  -H "X-Secregate-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: research-2026-08-17-001" \
  -d '{
    "query": "What factors affected data center revenue growth?",
    "ciks": ["0001045810"],
    "form_types": ["10-K", "10-Q"],
    "date_from": "2022-01-01",
    "date_to": "2026-08-17",
    "result_types": ["text", "table"],
    "top_k_by_type": {"text": 5, "table": 3}
  }'

HTTP/1.1 202 Accepted
Location: /v1/requests/7c3f92b0-04fa-4dac-9281-a55247431d34
Retry-After: 1

{
  "request_id": "7c3f92b0-04fa-4dac-9281-a55247431d34",
  "status": "queued",
  "poll": "/v1/requests/7c3f92b0-04fa-4dac-9281-a55247431d34",
  "billing": {"status": "pending", "credits": 3, "cost": 0.003, "currency": "EUR"}
}

To wait briefly in the initial connection, add Prefer: wait=N. The server caps N at 30 seconds. If processing is still underway, the response remains 202.

curl https://api.secregate.com/v1/requests/7c3f92b0-04fa-4dac-9281-a55247431d34 \
  -H "X-Secregate-Key: YOUR_API_KEY"

{
  "request_id": "7c3f92b0-04fa-4dac-9281-a55247431d34",
  "status": "completed",
  "priority": 10000,
  "received_at": "2026-08-17T12:00:00Z",
  "processing_started_at": "2026-08-17T12:00:00.190Z",
  "completed_at": "2026-08-17T12:00:02.060Z",
  "billing": {"status": "charged", "credits": 3, "cost": 0.003, "currency": "EUR"},
  "response": {
    "search_mode": "company_comparison",
    "company_count": 1,
    "results_by_company": [{
      "cik": "0001045810",
      "ticker": "NVDA",
      "company_name": "NVIDIA CORP",
      "text_results": [{
        "content_type": "text",
        "accession_number": "example-accession-number",
        "content": "Relevant filing passage…",
        "score": 0.89
      }],
      "table_results": [{
        "content_type": "table",
        "table_representation": "ixbrl",
        "table": {"representation": "ixbrl", "status": "resolved", "data": {"columns": [], "rows": []}}
      }]
    }]
  },
  "error": null
}

Search fields

Omit both ticker and ciks to search the complete currently indexed dataset. With several CIKs, results are separated by company and each requested result type receives its configured quota per company.

Table results

When a table can be resolved from iXBRL, table_representation is ixbrl and the structured columns, rows, facts, contexts and units are returned in table.data. If resolved iXBRL is unavailable, the API returns the filing-derived table as table_markdown and in the Markdown table envelope instead of returning an empty table payload.

{
  "content_type": "table",
  "table_representation": "markdown",
  "table_data": null,
  "table_markdown": "| Metric | 2025 | 2024 |\n|---|---:|---:|\n| Revenue | … | … |",
  "table": {
    "representation": "markdown",
    "status": "html_fallback",
    "reason": "no_resolved_ixbrl",
    "markdown": "| Metric | 2025 | 2024 |\n|---|---:|---:|\n| Revenue | … | … |"
  }
}

Character offsets and the parameters include_metadata and include_positions are not part of the current contract.

Asynchronous requests and batches

{
  "requests": [
    {"query": "Data center revenue", "ticker": "NVDA", "top_k": 5},
    {"query": "Export control risks", "ticker": "NVDA", "result_types": ["text"], "top_k": 10}
  ]
}

Use Idempotency-Key for safe retries. Reusing a key for the same customer returns the existing request or batch and avoids duplicate processing and billing. Batch items may additionally define their own idempotency_key.

Exact structured retrieval

Supply form_types and optionally filter by CIKs, accession numbers, dates, reporting person, transaction codes, share values, ownership percentage or section. Support depends on the specialist form pipeline and indexed dataset; this endpoint should not be treated as a universal parser for every SEC form.

MCP integration

Secregate exposes an MCP integration for semantic SEC search. MCP uses OAuth Bearer authentication and the same centralized retrieval infrastructure as REST. Client registration and authorization details are provided through the service's OAuth metadata; integration-specific values should be taken from that metadata rather than hard-coded.

Pricing

Every successful logical batch item is billed independently. Failed or cancelled semantic searches are not charged. Free includes a one-time 1,000-credit welcome grant and a 300-credit floor every 24 hours; Pro includes a 3,000-credit floor every 24 hours.

Status and errors

Observed performance

In the current deployment, an isolated sustained test at 10 requests per second measured approximately 2 seconds median server-side processing latency and below 3 seconds at p95. Public network time is additional. This is an observed measurement under normal test load, not a latency SLA; network path, filters, provider latency and concurrent load can change results.