financialfilings-com Agent Account API
Lets an AI agent get its own API key: sign up, check status, ask the owner to confirm, add a card.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/financialfilings-com:financialfilings-com-agent-account-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: FinancialFilings Agent Account API
version: 1.4.0
description: 'Filings and company data for listed companies across the G20 and Europe. Send your API key in the `X-API-Key` header on every request. New here? Start with the quickstart.
**Credits.** Every call costs credits, and each endpoint below shows its price. `X-Credits-Charged` on the response says what a call cost, and `GET /usage/` shows the month so far. A free account gets a monthly allowance. Webhooks are an Enterprise feature. Pricing: https://financialfilings.com/developers/
**Rate limits.** Responses carry `X-RateLimit-Burst-Limit` (a rate such as `50/second`), `X-RateLimit-Monthly-Limit`, `X-RateLimit-Monthly-Remaining` and `X-RateLimit-Monthly-Unit` (`requests` or `credits`). All four are strings and can be non-numeric (for example `Unlimited`); the last two are left out when they don''t apply.'
termsOfService: https://financialfilings.com/api-terms/
contact:
name: API Support
url: https://financialfilings.com/
email: api@financialfilings.com
servers:
- url: https://api.financialreports.eu
description: Production API Gateway
tags:
- name: Agent Account
description: 'Lets an AI agent get its own API key: sign up, check status, ask the owner to confirm, add a card.'
paths:
/agent/checkout-link/:
post:
operationId: agentCheckoutLink
description: Returns a Stripe link where the owner adds a card for pay-as-you-go. An unexpired link is reused (200).
summary: Create Checkout Link
tags:
- Agent Account
security:
- ApiKeyAuth: []
responses:
'201':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: ''
'200':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: Open link reused.
'403':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: ''
'409':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: ''
'429':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: ''
'502':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: ''
/agent/key-claim/:
post:
operationId: agentKeyClaim
description: After a 409 from signup, poll with its `claim_token`. Returns 202 until the owner approves, then the key (shown once). No API key needed.
summary: Claim an Existing Account's Key
tags:
- Agent Account
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AgentKeyClaimRequest'
required: true
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: Key (shown once).
'202':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: 'pending: poll again after Retry-After.'
'400':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: invalid_request / invalid_claim_token.
'410':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: claim_expired / claim_used / claim_refused.
'503':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: 'claim_unavailable: nothing changed, poll again after Retry-After.'
/agent/key/rotate/:
post:
operationId: agentKeyRotate
description: 'Replaces the key that made the call with a new one (shown once). Authenticate with the current key. Not available once the owner has logged in: they manage the key from the dashboard.'
summary: Rotate Agent Key
tags:
- Agent Account
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: ''
'429':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: ''
'403':
description: Missing or invalid API key, or the plan does not include this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
examples:
MissingCredentials:
summary: No X-API-Key header
value:
detail: Authentication credentials were not provided.
type: authentication_required
resolution: 'Send your API key in the X-API-Key request header, e.g. curl -H "X-API-Key: <your key>" https://api.financialreports.eu/filings/ . A browser address bar never sends this header. No key yet? Get a free one at https://financialfilings.com/accounts/api-dashboard/ .'
dashboard_url: https://financialfilings.com/accounts/api-dashboard/
InvalidKey:
summary: Unknown or inactive API key
value:
detail: Invalid or inactive API key.
PlanDoesNotPermit:
summary: Plan does not include this endpoint
value:
detail: Your current plan does not permit access. Requires a plan that includes **structured financials**.
/agent/owner-confirmation/:
post:
operationId: agentOwnerConfirmation
description: Emails the account owner a confirmation link. Poll `GET /agent/status` to see when they confirm.
summary: Request Owner Confirmation
tags:
- Agent Account
security:
- ApiKeyAuth: []
responses:
'202':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: ''
'409':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: ''
'429':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: ''
'403':
description: Missing or invalid API key, or the plan does not include this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
examples:
MissingCredentials:
summary: No X-API-Key header
value:
detail: Authentication credentials were not provided.
type: authentication_required
resolution: 'Send your API key in the X-API-Key request header, e.g. curl -H "X-API-Key: <your key>" https://api.financialreports.eu/filings/ . A browser address bar never sends this header. No key yet? Get a free one at https://financialfilings.com/accounts/api-dashboard/ .'
dashboard_url: https://financialfilings.com/accounts/api-dashboard/
InvalidKey:
summary: Unknown or inactive API key
value:
detail: Invalid or inactive API key.
PlanDoesNotPermit:
summary: Plan does not include this endpoint
value:
detail: Your current plan does not permit access. Requires a plan that includes **structured financials**.
/agent/signup/:
post:
operationId: agentSignup
description: 'Creates an account for the given email and returns its API key (shown once). No email is sent. The key starts in a small read-only sandbox; after that, data calls return 402 until the owner confirms (`POST /agent/owner-confirmation`) or adds a card (`POST /agent/checkout-link`). If the email already has an account, the 409 carries a `claim_token`: the owner can approve by email, and `POST /agent/key-claim` then returns their key.'
summary: Create an API Key as an AI Agent
tags:
- Agent Account
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AgentSignupRequest'
examples:
Request:
value:
email: dana@acme-quant.com
agent_name: acme-research-bot
required: true
responses:
'201':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: Key created (shown once).
'400':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: invalid_email / email_not_allowed / invalid_agent_name.
'409':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: account_exists, with claim_token / user_code / claim_endpoint.
'429':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: rate_limited.
'503':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: signup_paused / signup_unavailable.
/agent/status/:
get:
operationId: agentStatus
description: The account's state (`sandbox`, `unfunded`, `funded`, `active` or `blocked`), remaining sandbox calls, spend caps and any open checkout link.
summary: Get Agent Status
tags:
- Agent Account
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: ''
'403':
description: Missing or invalid API key, or the plan does not include this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDetail'
examples:
MissingCredentials:
summary: No X-API-Key header
value:
detail: Authentication credentials were not provided.
type: authentication_required
resolution: 'Send your API key in the X-API-Key request header, e.g. curl -H "X-API-Key: <your key>" https://api.financialreports.eu/filings/ . A browser address bar never sends this header. No key yet? Get a free one at https://financialfilings.com/accounts/api-dashboard/ .'
dashboard_url: https://financialfilings.com/accounts/api-dashboard/
InvalidKey:
summary: Unknown or inactive API key
value:
detail: Invalid or inactive API key.
PlanDoesNotPermit:
summary: Plan does not include this endpoint
value:
detail: Your current plan does not permit access. Requires a plan that includes **structured financials**.
'429':
description: Rate limit, plan quota or spend cap reached.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
examples:
BurstLimit:
summary: Too many requests per minute
value:
error: Too Many Requests
detail: Request was throttled. Expected available in 12 seconds.
retry_after_seconds: 12
scope: burst
type: burst_limit_exceeded
message: 'Rate limit reached: 120 requests per minute.'
resolution: 'Retry after 12 seconds (Retry-After header). Pay-as-you-go raises this to 50/sec: https://financialfilings.com/accounts/payg/'
rate_limit: 120/minute
payg_url: https://financialfilings.com/accounts/payg/
components:
schemas:
RateLimitError:
type: object
description: Body of a 429 response. The `Retry-After` header carries the same wait as `retry_after_seconds`. Only `detail` is always present.
properties:
detail:
type: string
description: A human-readable message describing the error.
error:
type: string
description: Always `Too Many Requests`.
retry_after_seconds:
type:
- integer
- 'null'
description: Seconds until the request may be retried, when known.
scope:
type:
- string
- 'null'
description: Which limit was hit, e.g. `burst`, `quota` or `payg_velocity`.
type:
type: string
description: Machine-readable error code, e.g. `burst_limit_exceeded`, `quota_limit_exceeded`, `daily_spend_cap_reached` or `monthly_spend_ceiling_reached`.
message:
type: string
description: A human-readable explanation of the limit.
resolution:
type: string
description: A human-readable hint on what to do next.
upgrade_url:
type: string
description: 'Where to upgrade: the pay-as-you-go card page for free accounts, else the plans page (quota errors).'
limit:
type: integer
description: The plan allowance that was used up (quota errors).
interval:
type: string
description: '`monthly` or `annual` (quota errors).'
resets_on:
type: string
format: date
description: UTC date the allowance resets (quota errors).
rate_limit:
type: string
description: The per-minute limit that refused the request, e.g. `120/minute` (burst errors).
payg_url:
type: string
description: Where to enable pay-as-you-go (quota and burst errors, when it applies).
dashboard_url:
type: string
description: Where to see current spend (spend-cap and spend-ceiling errors).
contact_url:
type: string
description: Where to ask for a higher limit (spend-cap and spend-ceiling errors).
required:
- detail
ErrorDetail:
type: object
properties:
detail:
type: string
description: A human-readable message describing the error.
type:
type: string
description: Machine-readable error code, e.g. `authentication_required`. Present on some errors only.
resolution:
type: string
description: A human-readable hint on how to fix the request. Present on some errors only.
error_type:
type: string
description: Machine-readable error code on validation errors. Present on some errors only.
required:
- detail
AgentKeyClaimRequest:
type: object
properties:
claim_token:
type: string
description: The `claim_token` returned in the signup 409 response.
required:
- claim_token
AgentSignupRequest:
type: object
properties:
email:
type: string
format: email
description: The account owner's real email address.
agent_name:
type: string
description: '1-64 chars: letters, digits, space, _ or -.'
required:
- agent_name
- email
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: 'Server-to-server API key authentication. Provide your key in the `X-API-Key` request header. Keys can be generated and rotated from your account dashboard: https://financialfilings.com/profile/'
CognitoJWT:
type: http
scheme: bearer
bearerFormat: JWT
description: 'AWS Cognito-issued JWT access token. Provide the token in the `Authorization` header as: `Authorization: Bearer <access_token>`. Tokens are issued via the Cognito hosted UI or the OAuth2 authorization code flow at `https://auth.financialreports.eu`.'