{"openapi":"3.1.0","info":{"title":"Open Well Data API","version":"1.3.0","summary":"Read-only catalogue metadata and links of Open Well Data.","description":"Read-only. GET, HEAD and OPTIONS only, plus POST on /mcp (remote MCP server, see x-mcp); any other method answers 405. No key or account is needed. An optional API key (X-API-Key header, requested at /key) raises the limits to 600 requests per minute, 50000 per UTC day and pages of up to 1000; a key in the URL answers 400. Documentation with examples: /docs. Data files are not served here: they are downloaded from Zenodo or from https://openwelldata.org. Every successful answer carries a `cite` field with the licence and attribution of the source. Requests are limited per client (60 per minute at present); over the limit the answer is 429 with Retry-After. Terms of use: /terms.","contact":{"email":"contact@openwelldata.org"}},"servers":[{"url":"https://api.openwelldata.org"}],"paths":{"/":{"get":{"summary":"Same as /v1","parameters":[],"responses":{"200":{"description":"Index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/v1":{"get":{"summary":"Index of the endpoints","parameters":[],"responses":{"200":{"description":"Index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/v1/health":{"get":{"summary":"Service status (does not read the catalogue)","parameters":[],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/v1/sources":{"get":{"summary":"Bilingual (English and Spanish) search in the catalogue of sources","parameters":[{"name":"q","in":"query","required":false,"description":"words in English or Spanish","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"country name","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"category code","schema":{"type":"string"}},{"name":"access","in":"query","required":false,"description":"access code","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"verification status","schema":{"type":"string"}},{"name":"data_type","in":"query","required":false,"description":"data type","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"at most 100 without a key, 1000 with an API key"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"format","in":"query","required":false,"description":"json (default) or csv. CSV carries the cite in the Link, X-OWD-Cite and X-OWD-Licence headers.","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"Matching sources","headers":{"Link":{"schema":{"type":"string"},"description":"rel=\"cite-as\" (catalogue DOI) and rel=\"license\""},"X-OWD-Cite":{"schema":{"type":"string"},"description":"the cite block, compact JSON in ASCII"},"X-OWD-Licence":{"schema":{"type":"string"}},"Content-Disposition":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}},"text/csv":{"schema":{"type":"string"},"description":"RFC 4180, CRLF, a header row with fixed columns"}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/v1/sources/{id}":{"get":{"summary":"One source record, as published in data/source/<id>.json","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,120}$"}}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/v1/collections":{"get":{"summary":"Standardized collections, with Zenodo links when published","parameters":[{"name":"q","in":"query","required":false,"description":"words in English or Spanish","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"country name","schema":{"type":"string"}},{"name":"data_type","in":"query","required":false,"description":"data type","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"published or coming","schema":{"type":"string"}},{"name":"licence","in":"query","required":false,"description":"SPDX id (e.g. CC-BY-4.0) or licence family (e.g. cc-by, nlod, public-domain, equinor-volve); see /docs#filters","schema":{"type":"string"}},{"name":"commercial_use","in":"query","required":false,"description":"of the source data, from source_licence","schema":{"type":"string","enum":["allowed","not_allowed","unknown"]}},{"name":"copy_commercial_use","in":"query","required":false,"description":"of the Open Well Data copy, from copy_licence","schema":{"type":"string","enum":["allowed","not_allowed","unknown"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"at most 100 without a key, 1000 with an API key"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"format","in":"query","required":false,"description":"json (default) or csv. CSV carries the cite in the Link, X-OWD-Cite and X-OWD-Licence headers.","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"Matching collections","headers":{"Link":{"schema":{"type":"string"},"description":"rel=\"cite-as\" (catalogue DOI) and rel=\"license\""},"X-OWD-Cite":{"schema":{"type":"string"},"description":"the cite block, compact JSON in ASCII"},"X-OWD-Licence":{"schema":{"type":"string"}},"Content-Disposition":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}},"text/csv":{"schema":{"type":"string"},"description":"RFC 4180, CRLF, a header row with fixed columns"}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/v1/collections/{id}":{"get":{"summary":"One collection, with url and sha256 of each package file (files=[] and files_note when the catalogue has no file list)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,120}$"}}],"responses":{"200":{"description":"The collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/v1/datasets":{"get":{"summary":"Datasets with a reader: licence, policy and citation","parameters":[],"responses":{"200":{"description":"The datasets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/v1/datasets/{id}":{"get":{"summary":"One dataset, with how to load it","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,120}$"}}],"responses":{"200":{"description":"The dataset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/v1/openapi.json":{"get":{"summary":"This description","parameters":[],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/terms":{"get":{"summary":"Terms of use (HTML)","parameters":[],"responses":{"200":{"description":"Terms of use","content":{"text/html":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/docs":{"get":{"summary":"Documentation (HTML): limits, citation and licences, examples, MCP","parameters":[],"responses":{"200":{"description":"Documentation page","content":{"text/html":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{},{"ApiKey":[]}]}},"/key":{"get":{"summary":"Form to request an API key (HTML, with Turnstile)","parameters":[],"responses":{"200":{"description":"The form","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/key/delete":{"get":{"summary":"Form to delete a key without it: a confirmation link is sent by email (HTML)","parameters":[],"responses":{"200":{"description":"The form","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/key/confirm":{"get":{"summary":"Page of an email link, with a button (the link is used by POST /v1/keys/confirm)","parameters":[{"name":"t","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The page","content":{"text/html":{"schema":{"type":"string"}}}},"400":{"description":"Link expired or used","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/privacy":{"get":{"summary":"Privacy notice of the API keys (HTML)","parameters":[],"responses":{"200":{"description":"The notice","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/v1/keys":{"post":{"summary":"Request a key: sends a one-use link valid 24 hours to the address (same answer whether or not it has a key)","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}}}},"description":"Fields: email, org_type, country (ISO 3166-1 alpha-2), use, organization (optional), use_text (optional, 300 characters), list_organization and statement (optional, unticked), cf-turnstile-response (Turnstile token, action key-request).","responses":{"202":{"description":"Sent, if the address can receive it","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/keys/confirm":{"post":{"summary":"Use an email link: shows the key once (issue) or deletes everything of the address (delete)","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Done (form)","content":{"text/html":{"schema":{"type":"string"}}}},"201":{"description":"The key, shown once (JSON)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/keys/delete-request":{"post":{"summary":"Without the key: sends a one-use deletion link to the address, if it has a key (same answer either way)","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}}}},"responses":{"202":{"description":"Sent, if the address has a key","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/keys/me":{"get":{"summary":"Everything kept about your key","security":[{"ApiKey":[]}],"parameters":[],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRecord"}}}},"401":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Withdraw the optional consents: {\"list_organization\": false} and/or {\"statement\": false}","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"list_organization":{"const":false},"statement":{"const":false}}}}}},"responses":{"200":{"description":"The record after the change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRecord"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Delete the key and everything linked to it","security":[{"ApiKey":[]}],"parameters":[],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"}}}}},"x-mcp":{"endpoint":"/mcp","endpoint_note":"exactly /mcp; /mcp/ answers 405","method":"POST","transport":"Streamable HTTP; answers in application/json, no SSE stream, no sessions; GET answers 405","protocol":"JSON-RPC 2.0; methods initialize, ping, tools/list, tools/call; notifications answer 202","protocol_versions":["2025-11-25","2025-06-18","2025-03-26","2024-11-05"],"tools":["search_sources","get_source","search_collections","get_collection","list_datasets","describe_dataset","cite","variables","standard_channels","standard_name","search_by_variables"],"argument_errors":"tool result with isError: true (unknown tools: JSON-RPC error -32602)","max_body_bytes":65536,"read_only":true,"docs":"/docs#mcp","api_key":"optional X-API-Key header, the same limits as the routes"},"components":{"schemas":{"Cite":{"type":"object","required":["catalogue","preprint","how_to_cite"],"properties":{"how_to_cite":{"type":"string"},"catalogue":{"type":"object","properties":{"doi":{"type":"string"},"url":{"type":"string"},"citation":{"type":"string"},"licence":{"type":"string"}}},"preprint":{"type":"object","properties":{"doi":{"type":"string"},"url":{"type":"string"}}},"collection":{"type":"object","description":"DOI of the collection, when it has one"},"source":{"type":"object","description":"Licence and attribution of the source, as the record states them"},"items":{"type":"array","description":"Licence, attribution and DOI of each record in a list","items":{"type":"object"}}}},"Answer":{"type":"object","required":["cite"],"properties":{"cite":{"$ref":"#/components/schemas/Cite"}},"additionalProperties":true},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"KeyRecord":{"type":"object","description":"What is kept about a key (see /privacy)"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests from this client","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Optional. Requested at /key; see /docs#keys and /privacy."}}},"x-cite":{"how_to_cite":"Cite the original provider of each source you use, with its licence and attribution as given here; cite the Open Well Data catalogue and the preprint when they helped your work.","catalogue":{"doi":"10.5281/zenodo.23961755","url":"https://doi.org/10.5281/zenodo.23961755","citation":"Delgado-Uriarte, D. (2026). Open Well Data catalogue [Data set]. Zenodo. https://doi.org/10.5281/zenodo.23961755","licence":"CC BY-NC 4.0 (catalogue records only; each source keeps its own licence)"},"preprint":{"doi":"10.31223/X5NJ8V","url":"https://doi.org/10.31223/X5NJ8V"}}}