Two specialized utilities. REST or MCP.
Caskveil exposes specialized services through consistent REST and MCP interfaces. Keys are scoped to one service, so the SEC and Document Intelligence operations each require their own credential.
Create an organization workspace, authorize an agent, and reveal a service-scoped bearer key once. Each successful action uses its configured credit rate; failed operations use zero credits. Top-ups are available in one-time $10, $25, and $50 bundles.
Authenticated JSON over HTTPS
POST /v1/financial/sec/analyzeSend the request body below with Authorization: Bearer YOUR_API_KEY. The optional Idempotency-Key header lets a retry reuse the same operation.
Streamable HTTP MCP endpoint
POST /mcpInitialize the MCP connection, then call caskveil_sec_analyze with the same bearer key and request fields as REST.
Document Intelligence
Structured extraction with source evidence.
Submit pasted UTF-8 business document text up to 16 KiB to receive a document type, summary, key facts with exact evidence excerpts, uncertainties, and limitations. PDF, image, and office-file upload are not supported in this text-input slice.
POST /v1/documents/analyzeUse a Document Intelligence scoped bearer key and send { "text": "…" }.
Every REST request needs an Idempotency-Key. Without payment headers, REST uses prepaid credits and charges 1 credit only after a validated result; insufficient balance returns 402 insufficient_credits. Failed admitted operations record zero usage and zero charge.
The optional x402 rate is $0.50 USDC and is available only when a receiving address and facilitator are configured. To use it, send X-PAYMENT. To get a challenge first, send X-Caskveil-Payment-Mode: x402 without proof. An x402 failure never falls back to prepaid credits. Reusing an idempotency key with different input or a different payment mode returns 409.
POST /mcp · caskveil_document_analyzeThe same text field and structured response are available to an authenticated Document Intelligence key.
Published default prepaid rate: $1 USD / 1 Caskveil credit per validated successful analysis; failed analyses are not charged. Optional x402: $0.50 USDC per analysis, available only when a receiving address and facilitator are configured.
The tester uses a fictional invoice labeled synthetic; that sample does not indicate service availability.
Open the Document Intelligence testerSEC REST quickstart
Submit one filing for analysis.
The public POST /v1/financial/sec/analyze path rewrites to the existing SEC analysis handler. Its strict JSON request contract is also used by the MCP tool.
Sign in or create and verify an account managed by Better Auth, then open the workspace and agent key flow. If you have not set it up yet, authorize an organization and agent there, then create a key for SEC Filing AI (caskveil.sec.analyze). The key is revealed once; store it in server-side secret storage. The REST request uses this bearer key, not a browser session cookie.
curl --request POST "$APP_BASE_URL/v1/financial/sec/analyze" \
--header "Authorization: Bearer $SEC_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: apple-2024-risk-review" \
--data '{
"company": {
"cik": "0000320193",
"name": "Apple Inc."
},
"filing": {
"accessionNumber": "0000320193-24-000123",
"form": "10-K"
},
"question": "What material risks does this filing describe?"
}'Set APP_BASE_URL to your deployment origin and SEC_API_KEY to the key you just created. The Idempotency-Key header is optional; reuse the same value only when retrying the same request.
company.cikis exactly 10 digits; company name is optional.filing.accessionNumberuses 10-2-6 digits; filing form is optional.questionis required and must be 8–2,000 characters.
MCP call shape
Use the same operation through MCP.
After initialization, call the named tool at /mcp. Its arguments follow the shared request contract above.
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "caskveil_sec_analyze",
"arguments": { /* same request fields as REST */ }
}
}A successful response includes an answer, 1–12 key findings, and 1–12 limitations. Each finding includes a filing section and source URL.
The answer is limited to 6,000 characters; a finding to 900; a section label to 140; and each limitation to 500. Citations point to filing sources and do not make the result investment advice.
Success · usage quantity 1 · charged true
Failure · usage quantity 0 · charged false
SEC Filing AI is provisionally $1 USD / 1 credit per successful analysis. Document Intelligence uses its separately configured rate of $1 USD / 1 credit. Both services charge only after a valid result, regardless of REST or MCP.
Answer text and filing citations vary by request. This example follows the structured REST response contract.
{
"requestId": "sec_req_01JMG9KQ2P4H7V8T5W6X3Y1Z0A",
"status": "succeeded",
"service": "caskveil.sec.analyze",
"result": {
"answer": "The filing describes risks related to competition, supply chains, and dependence on third-party networks.",
"keyFindings": [
{
"finding": "Competition may affect the company's business, results, and financial condition.",
"sourceSection": "Risk Factors",
"sourceUrl": "https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/index.html"
}
],
"limitations": [
"This analysis summarizes the cited filing and is not investment advice."
]
},
"usage": { "unit": "sec_analysis", "quantity": 1 },
"price": {
"currency": "CASKVEIL_CREDITS",
"amount": 1,
"charged": true,
"unitPriceUsd": 1
},
"timestamp": "2025-02-12T18:30:00.000Z"
}A successful analysis has usage.quantity: 1 and is charged. price.amount is the number of Caskveil credits; unitPriceUsd is optional USD attribution.
Authentication and request validation errors use simple error objects. Analysis outcomes use the structured response with status: failed.
401— missing or invalid bearer key.403— revoked key or a key scoped to a different service.400— invalid JSON or fields that fail the strict request contract; schema field errors appear inerrors.
Structured analysis failures include:
402insufficient_credits404filing_not_found409request_in_progressoridempotency_key_failed502SEC/AI provider or invalid analysis output
Failed analysis has usage.quantity: 0, price.amount: 0, and price.charged: false.
Agent access and billing
Set up your agent in the workspace.
Create the organization and agent you authorize, store its one-time API key securely, then create a separately scoped key for each service and buy shared credits from the workspace. Checkout verifies the buyer-paid amount before the balance changes. Each key exposes only its matching REST operation and MCP tool.