Source catalog metadata, freshness and integration status
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/openmercantil:openmercantil-sources-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
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: 3.2.0
info:
title: Openmercantil Sources API
contact:
name: OpenMercantil
url: https://openmercantil.es/soporte
email: social@openmercantil.es
termsOfService: https://openmercantil.es/terminos-de-uso
x-refined-note:
- x-account-segment-contract differs across the merged source definitions and was not carried
- x-company-identity-contract differs across the merged source definitions and was not carried
- x-contract-status differs across the merged source definitions and was not carried
- x-corrections differs across the merged source definitions and was not carried
- x-dcat-catalog differs across the merged source definitions and was not carried
- x-language differs across the merged source definitions and was not carried
- x-methodology differs across the merged source definitions and was not carried
- x-publisher differs across the merged source definitions and was not carried
- x-rate-limit differs across the merged source definitions and was not carried
- x-sources differs across the merged source definitions and was not carried
- x-spatial differs across the merged source definitions and was not carried
- x-temporal differs across the merged source definitions and was not carried
version: '1.0'
description: 'Operations tagged Sources across 2 of this provider''s published API definitions: openmercantil-openapi-1.9.3.json, openmercantil-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://openmercantil.es
description: Production
tags:
- name: Sources
description: Source catalog metadata, freshness and integration status
paths:
/api/v1/sources/freshness:
get:
operationId: getSourcesFreshness
parameters:
- $ref: '#/components/parameters/IfNoneMatchHeader'
tags:
- Sources
summary: Per-source freshness map
description: Return a minimized freshness projection only for sources authorized by the versioned public-source catalog. The timestamp comes from the offline projection, never request time. Its ETag is bound to the shared asv1 stats generation and uses 60-second must-revalidate caching. Unknown, review and restricted sources are omitted. Connector health, errors, schedules and row counts are never exposed.
security:
- {}
- apiKey: []
- bearerAuth: []
x-api-credential-scope: integrations:read
x-rate-limit: plan policy (see info.x-rate-limit)
responses:
'200':
description: Freshness map
headers:
X-Data-Sources:
$ref: '#/components/headers/XDataSources'
X-Source-Catalog-Version:
$ref: '#/components/headers/XSourceCatalogVersion'
X-Attribution-Required:
$ref: '#/components/headers/XAttributionRequired'
ETag:
$ref: '#/components/headers/EntityTag'
X-OpenMercantil-Stats-Generation:
$ref: '#/components/headers/StatsGeneration'
Cache-Control:
schema:
type: string
const: public, max-age=60, must-revalidate
content:
application/json:
schema:
type: object
description: Fail-closed public projection. Operational ingestion telemetry is intentionally absent.
properties:
generated_at:
type:
- string
- 'null'
format: date-time
description: Offline projection generation time; null only for a legacy cache without provenance.
global:
type: object
properties:
date:
type:
- string
- 'null'
format: date-time
label:
type:
- string
- 'null'
status:
type: string
enum:
- current
- stale
- unknown
source_catalog_version:
type: string
sources:
type: array
items:
$ref: '#/components/schemas/PublicSourceMetadata'
count:
type: integer
_legal_notice:
type: string
'304':
description: The authorized freshness representation and shared stats generation have not changed
headers:
ETag:
$ref: '#/components/headers/EntityTag'
X-OpenMercantil-Stats-Generation:
$ref: '#/components/headers/StatsGeneration'
Cache-Control:
schema:
type: string
const: public, max-age=60, must-revalidate
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
description: The required offline freshness projection is absent, or the public-source legal policy cannot produce an authorized projection. This endpoint fails closed and never falls back to live connector telemetry.
headers:
Retry-After:
description: Seconds before retrying when the offline projection is absent.
schema:
type: integer
minimum: 0
content:
application/json:
schema:
$ref: '#/components/schemas/OfflineProjectionError'
examples:
projection_required:
value:
error: offline_projection_required
projection: sources_freshness_v5
legal_layer_unavailable:
value:
error: legal_layer_unavailable
servers:
- url: https://openmercantil.es
description: Production
/api/v1/sources/status:
get:
operationId: getSourcesStatus
parameters:
- $ref: '#/components/parameters/IfNoneMatchHeader'
tags:
- Sources
summary: Minimized public source metadata
description: Return only public catalog metadata and a coarse data date/freshness. Its ETag is bound to the shared asv1 stats generation and uses 60-second must-revalidate caching. This endpoint is not an operator health probe and does not expose connector status, errors, schedules, source URLs or item counts.
x-rate-limit: free 60/min · 200/day
responses:
'200':
description: Fail-closed public source projection
headers:
X-Data-Sources:
$ref: '#/components/headers/XDataSources'
X-Source-Catalog-Version:
$ref: '#/components/headers/XSourceCatalogVersion'
X-Attribution-Required:
$ref: '#/components/headers/XAttributionRequired'
ETag:
$ref: '#/components/headers/EntityTag'
X-OpenMercantil-Stats-Generation:
$ref: '#/components/headers/StatsGeneration'
Cache-Control:
schema:
type: string
const: public, max-age=60, must-revalidate
content:
application/json:
schema:
$ref: '#/components/schemas/PublicSourceStatusResponse'
'304':
description: The minimized source-status representation and shared stats generation have not changed
headers:
ETag:
$ref: '#/components/headers/EntityTag'
X-OpenMercantil-Stats-Generation:
$ref: '#/components/headers/StatsGeneration'
Cache-Control:
schema:
type: string
const: public, max-age=60, must-revalidate
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/PublicReadUnavailable'
servers:
- url: https://openmercantil.es
description: Production
/api/v1/company/{slug}/grants:
get:
tags:
- Sources
summary: List Company Grants From BDNS
operationId: getCompanyGrants
description: Return public grants associated with the company from the BDNS dataset (v1.2).
parameters:
- name: slug
in: path
required: true
schema:
type: string
example: inditex-sa-a15075062
responses:
'200':
description: Grants list
content:
application/json:
schema:
type: object
additionalProperties: true
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests_2'
servers:
- url: https://openmercantil.es
description: Production
/api/v1/company/{slug}/sanctions:
get:
tags:
- Sources
summary: List Company Sanctions
operationId: getCompanySanctions
description: Return sanctions hits associated with the company from OpenSanctions and competition authorities (v1.2).
parameters:
- name: slug
in: path
required: true
schema:
type: string
example: inditex-sa-a15075062
responses:
'200':
description: Sanctions list
content:
application/json:
schema:
type: object
additionalProperties: true
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests_2'
servers:
- url: https://openmercantil.es
description: Production
/api/v1/company/{slug}/cnmv:
get:
tags:
- Sources
summary: Get CNMV Records For Company
operationId: getCompanyCnmv
description: Return CNMV (Spanish securities regulator) records for the company (v1.2).
parameters:
- name: slug
in: path
required: true
schema:
type: string
example: inditex-sa-a15075062
responses:
'200':
description: CNMV records
content:
application/json:
schema:
type: object
additionalProperties: true
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests_2'
servers:
- url: https://openmercantil.es
description: Production
components:
schemas:
ErrorResponse:
type: object
description: Closed compatibility envelope for public/account errors. Route-specific schemas narrow these fields further where required.
required:
- error
properties:
error:
type: string
minLength: 1
message:
type: string
detail:
type: string
code:
type: string
status:
type:
- integer
- string
projection:
type: string
reason:
type: string
source_catalog_version:
type: string
allowed_parameters:
type: array
uniqueItems: true
items:
type: string
slug:
type: string
key:
type: string
maximum:
type: integer
minimum: 1
parameter:
type: string
fields:
type: array
items:
type: string
max_bytes:
type: integer
minimum: 1
allowed:
type: array
items:
$ref: '#/components/schemas/JsonValue'
valid:
type: array
items:
$ref: '#/components/schemas/JsonValue'
date:
type: string
login_url:
type: string
plan:
type: string
limited_by:
type: string
enum:
- minute
- day
daily_limit:
type: integer
minimum: 1
reset_at:
type: integer
minimum: 1
reset_at_human:
type: string
format: date-time
retry_after_s:
type: integer
minimum: 1
retry_after:
type: integer
minimum: 1
upgrade:
type: string
format: uri
upgrade_url:
type: string
action:
type: string
limit:
type: integer
minimum: 0
remaining:
type: integer
minimum: 0
needed:
type: integer
minimum: 0
shortfall:
type: integer
minimum: 0
ok:
type: boolean
_alias_of:
type: string
additionalProperties: false
PublicSourceMetadata:
type: object
additionalProperties: false
required:
- slug
- name
- license
- attribution_required
- reuse_conditions
- policy_effective_date
- catalog_version
- freshness
properties:
slug:
type: string
name:
type: string
license:
type: string
license_url:
type:
- string
- 'null'
format: uri
attribution_required:
type: boolean
attribution_text:
type:
- string
- 'null'
official_url:
type:
- string
- 'null'
format: uri
reuse_conditions:
type: string
description: Condiciones de reutilizacion que el consumidor debe conservar al presentar o transformar el dato.
policy_effective_date:
type: string
format: date
reviewed_at:
type:
- string
- 'null'
format: date
data_updated_at:
type:
- string
- 'null'
format: date-time
catalog_version:
type: string
freshness:
type: string
enum:
- current
- stale
- unknown
JsonValue:
description: A JSON value used only inside explicitly documented extension maps.
oneOf:
- type:
- string
- number
- boolean
- 'null'
- type: array
items:
$ref: '#/components/schemas/JsonValue'
- type: object
additionalProperties:
$ref: '#/components/schemas/JsonValue'
ProjectionUnavailableError:
type: object
description: Fail-closed projection outage. Clients must not reinterpret this response as an empty or negative result.
required:
- error
- detail
- projection
properties:
error:
type: string
const: projection_unavailable
detail:
type: string
projection:
type: string
additionalProperties: false
OfflineProjectionError:
type: object
required:
- error
properties:
error:
type: string
projection:
type:
- string
- 'null'
derivation:
type:
- string
- 'null'
detail:
type:
- string
- 'null'
additionalProperties: false
PublicSourceStatusResponse:
type: object
additionalProperties: false
required:
- generated_at
- source_catalog_version
- count
- sources
- _legal_notice
properties:
generated_at:
type: string
format: date-time
source_catalog_version:
type: string
count:
type: integer
minimum: 0
sources:
type: array
items:
$ref: '#/components/schemas/PublicSourceMetadata'
_legal_notice:
type: string
SourcesStatus:
type: object
properties:
sources:
type: array
items:
type: object
properties:
name:
type: string
last_ingested:
type:
- string
- 'null'
status:
type: string
additionalProperties: true
additionalProperties: true
ErrorResponse_2:
type: object
properties:
error:
type: string
message:
type: string
additionalProperties: true
responses:
PublicReadUnavailable:
description: The public read failed closed because its legal source catalog, subject classification, bounded projection, database helper or required artifact is unavailable. Clients must not infer an empty result.
headers:
Cache-Control:
description: Unavailable public reads are never cacheable.
schema:
type: string
const: no-store
Retry-After:
description: Optional number of seconds to wait before retrying.
schema:
type: integer
minimum: 1
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ProjectionUnavailableError'
- $ref: '#/components/schemas/ErrorResponse'
examples:
legal_layer:
value:
error: legal_layer_unavailable
company_identity:
value:
error: company_public_projection_unavailable
projection:
value:
error: projection_unavailable
detail: La proyección pública requerida no está disponible.
projection: wikidata_company_v1
TooManyRequests:
description: Rate limit exceeded
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
TooManyRequests_2:
description: Rate limit exceeded
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Limit:
description: Maximum requests per window (60 per minute by IP on the public anonymous tier).
schema:
type: integer
X-RateLimit-Remaining:
description: Remaining requests in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp when the rate-limit counter resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
headers:
StatsGeneration:
description: Exact shared generation of the active CCAA, sector, sources and global-counters bundle.
schema:
type: string
pattern: ^asv1-[a-f0-9]{64}$
XAttributionRequired:
description: Optional. When present, comma-separated public source aliases whose attribution terms must accompany reuse.
schema:
type: string
minLength: 1
pattern: ^[a-z0-9][a-z0-9_.-]*(,[a-z0-9][a-z0-9_.-]*)*$
example: placsp
XSourceCatalogVersion:
description: Mandatory on every successful public GET. Exact version of the legal source catalog used to authorize the response.
schema:
type: string
minLength: 1
example: 2026-07-12.2
XDataSources:
description: Comma-separated aliases from the active public source catalog that contributed to the response. Omitted only when a valid exact filter returns an empty representation with zero contributing sources.
schema:
type: string
minLength: 1
pattern: ^[a-z0-9][a-z0-9_.-]*(,[a-z0-9][a-z0-9_.-]*)*$
example: borme,placsp
EntityTag:
description: Strong generation-bound entity tag for conditional GET.
schema:
type: string
pattern: ^"[a-f0-9]{64}"$
parameters:
IfNoneMatchHeader:
name: If-None-Match
in: header
required: false
description: Optional RFC 9110 entity-tag validator. Weak validators, comma-separated validator lists and `*` are accepted.
schema:
type: string
minLength: 1
maxLength: 8192
securitySchemes:
cookieAuth:
type: apiKey
in: cookie
name: ob_sess
description: Browser session cookie set after login at /mi-cuenta/login. Mutations also require X-CSRF-Token header (obtain via GET /api/v1/user/me).
apiKey:
type: apiKey
in: header
name: X-API-Key
description: Optional opaque omk_* API credential for public GETs. Anonymous access remains valid; a credential with the operation's x-api-credential-scope (or public:read) selects its account quota. Never place credentials in query strings.
bearerAuth:
type: http
scheme: bearer
bearerFormat: opaque omk_* credential
description: 'Optional Authorization: Bearer transport for the same opaque omk_* API credential accepted by X-API-Key. It is not a JWT or OAuth access token.'
sessionCookie:
type: apiKey
in: cookie
name: session
description: Session cookie issued after web sign-in, required only for billing endpoints.
externalDocs:
description: Documentación narrativa con ejemplos en curl/Python/JavaScript
url: https://openmercantil.es/api/documentacion
x-refined-from:
- openmercantil-openapi-1.9.3.json
- openmercantil-openapi.yml