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. GET /v1/coverage is public and does not require an API key. Obtain and manage your API key in the dashboard after signing in.

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: REPLACE_WITH_UNIQUE_KEY_FOR_THIS_SEARCH" \
  -d '{
    "query": "What factors affected data center revenue growth?",
    "ciks": ["0001045810"],
    "form_types": ["10-K", "10-Q"],
    "date_from": "2022-01-01",
    "top_k": 10
  }'

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": 1, "cost": 0.001, "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.

If the initial response is 200, consume its top-level results directly. A polled completed request instead wraps the search output in response. Poll until completed, failed or cancelled; do not poll indefinitely after a terminal state. Timestamps and hit contents below are illustrative, not measured response-time promises.

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": 1, "cost": 0.001, "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": "example-accession-number",
        "content": "Relevant filing passage…",
        "score": 0.89
      }],
      "table_results": [{
        "content_type": "table",
        "accession": "example-accession-number",
        "content": "Filing-derived table text…",
        "table_data": null,
        "table_representation": null,
        "table_markdown": null,
        "table": null
      }]
    }]
  },
  "error": null
}

Search fields

Omit both ticker and ciks for a global search. With several CIKs, results are separated by company and limits apply per company. By default, the ten highest-scoring passages are selected regardless of source type. Explicit quotas reserve slots by type; unavailable slots are not filled with the other type and fewer results can be returned when matching distinct sources are unavailable.

// Only tables
"result_types": ["table"]

// Only text passages
"result_types": ["text"]

// Two text passages and eight tables
"top_k_by_type": {"text": 2, "table": 8}

// Explicit equal mix
"top_k_by_type": {"text": 5, "table": 5}

Table results

A table hit is identified by content_type: "table". Always read content for the source passage. The current public Ubuntu retrieval path returns filing-derived table text; table_data, table, table_representation and table_markdown may all be null. Do not assume every hit has structured rows or Markdown.

If a source supplies validated iXBRL, table_representation can be ixbrl with data in table.data. If a source supplies a Markdown fallback, its representation is markdown. These are optional representations, not guaranteed output for the current dataset.

{
  "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 a new Idempotency-Key for each distinct logical search or batch and reuse it only for retries of that same operation. Reusing a key for the same customer returns the existing request or batch; changing the query with the same key does not create a new search. 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

Connect MCP clients to https://api.secregate.com/mcp using OAuth Bearer authentication. Authorization metadata is available at /.well-known/oauth-authorization-server and resource metadata at /.well-known/oauth-protected-resource. Legacy SSE clients use /mcp/sse. The search tool defaults to ten results ranked across text and tables; optional top_k_text and top_k_tables specify exact per-company quotas totaling at most top_k (maximum ten). Client access must be configured for the integration; do not assume dynamic registration is available.

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. Every 24 hours, a balance below 100 is topped up to 100; a balance of 100 or more stays unchanged. Daily top-ups do not accumulate, and there is no monthly replenishment. Pro limits, scope and pricing are agreed individually. For production and commercial use, contact nithard@portrak.com.

Status and errors

Rate limits and processing time

Request admission limits are separate from completed-search throughput. Accepted searches are queued and processing time depends on filters, company count, storage reads and concurrent work. HTTP 202 does not mean retrieval has finished. Honor Retry-After and poll the request endpoint; no fixed latency or completed-search throughput is guaranteed.