Scope and authentication
This is a public-information API for understanding CareOps software. It is not the proposed Care Access API. It cannot obtain provider availability, submit a care referral, book an assessment, change records or accept payment. No API key or sign-in is needed for these public product facts. Never send care details, staff information, credentials or confidential documents. Existing private CareOps pages retain their authentication and tenant controls.
Versioning and deprecation
Use GET https://getcareops.co.uk/api/v1/public/careops. The optional API-Version request header accepts only 1; the response echoes API-Version: 1. GET /api/public/careops remains a supported alias with the same success body. Neither route is deprecated and no retirement date is scheduled. Do not send query parameters; unsupported ones return 400 rather than being silently ignored.
Breaking changes require a new major URL such as /api/v2; fixes that preserve the documented contract may ship within v1. Before a planned removal we will publish the affected paths, migration instructions and dates on this page, link that policy with rel="deprecation", and signal deprecation using RFC 9745 Deprecation (a Structured Field Date). A scheduled shutdown will additionally use RFC 8594 Sunset (an HTTP-date). Those date headers are absent today because no shutdown has been announced. No arbitrary expiry date has been invented for the existing endpoint.
Rate limits and retry behaviour
The current public REST routes enforce a burst limit of 60 requests per 60-second fixed window, per recognised client IP and serving function instance. Successful and rejected application requests, HEAD and OPTIONS consume allowance; attempts after exhaustion do not extend the window. Vercel-supplied IP values are used only within Vercel; unidentified clients share an instance-local bucket. Only salted hashes are kept transiently in process memory. No database, persistent IP log, new paid service or account quota is used.
RateLimit-Policy: "public-instance";q=60;w=60 describes the policy. RateLimit: "public-instance";r=59;t=45 describes remaining requests and reset delay in seconds. These fields follow draft-ietf-httpapi-ratelimit-headers-11, which is an Internet-Draft, not a published RFC. X-RateLimit-Limit/Remaining/Reset are compatibility fields; X-RateLimit-Reset is UNIX seconds, not a delay. On 429 the application returns Problem Details plus Retry-After. Wait at least that delay, then retry more slowly with jitter.
This is genuine local burst enforcement, NOT a shared or durable quota across regions, cold starts or function instances. Counters can differ between routes or instances and reset after process recycling. Follow the current response, not an assumed global allowance. A shared datastore or managed distributed limiter must be separately configured and tested before operational or paid API usage. Network/hosting-layer limits can also apply.
Typed responses and function calling
Both documented GET operations have distinct operationIds, typed optional version headers and fully typed success fields, nested contacts, links, arrays and booleans. OpenAPI components define CareOpsPublicInfo and ProblemDetails. The legacy operationId getCareOpsPublicInfo is preserved; new integrations can use getCareOpsPublicInfoV1. The public MCP methods remain JSON-RPC and are not changed to REST Problem Details.
Every application-owned REST failure has an HTTP status matching its problem status and Content-Type: application/problem+json. It includes type, title, status, detail, instance, code, message, resolution and requestId. Branch on type/code, not message text. Instance is an opaque urn:uuid; it never reflects query strings, personal data or credentials. Unexpected exceptions are sanitised. Errors intercepted by the hosting platform before the application runs cannot be guaranteed to use our schema.
Command-line client
A first-party read-only Node.js client is available as a direct download. Download /cli/careops.mjs, inspect it, then run node careops.mjs info or node careops.mjs openapi. Use node careops.mjs --help for commands. It requires Node.js 20 or later, has no dependencies or install scripts, uploads no data and uses no credentials. It rejects external redirects, limits response size, has a timeout and reports structured API failures without automatic retries.
The output is JSON. Exit status 0 means success, 1 means an API error and 2 means an invalid argument, network failure or invalid response. The package is prepared but NOT published on npm, PyPI or Homebrew: a founder-approved publishing identity and authenticated publisher session are still required. There is no claimed npx command or registry installation.
API route not found (404)
Code NOT_FOUND. An unknown /api path has no operation. Use the versioned public-information URL or consult OpenAPI. Do not interpret a 404 as evidence that a care provider is unavailable.
Method not allowed (405)
Code METHOD_NOT_ALLOWED. The public-information resource accepts GET, HEAD and OPTIONS only. Inspect Allow. No request body is processed and no write takes place.
JSON representation required (406)
Code NOT_ACCEPTABLE. Send Accept: application/json for a success response. Failure responses use application/problem+json, including when that media type was not explicitly requested.
Unsupported query parameter (400)
Code INVALID_QUERY. Remove the query string: this public-information resource has no search, personal-data or pagination parameters. Unknown inputs are rejected without echoing their values.
Unsupported API version (400)
Code UNSUPPORTED_API_VERSION. Set API-Version to 1 or omit the optional header. An unknown URL version has no route and returns NOT_FOUND.
Request rate exceeded (429)
Code RATE_LIMITED. The serving instance has exhausted this client allowance. Use Retry-After and the current RateLimit fields; avoid immediate or parallel retries. The error does not indicate any care availability or account balance.
Unexpected application error (500)
Code INTERNAL_ERROR. Retry later. Contact operations@getcareops.co.uk with the returned requestId if needed. Do not send credentials or care documents. Stack traces and internal exception details are not exposed; the service does not provide a public diagnostic-error trigger.