Decode Compound ID API

Endpoint

Contract

Send mymolecules-api-version with 2026-07-10 to use the documented response contract.

{
  "data": {},
  "meta": {
    "request_id": "req_...",
    "api_version": "2026-07-10"
  }
}

Headers

Request

• x-api-key required - Server-side API key for your integration.
• mymolecules-api-version required 2026-07-10 - Use the latest stable API version: 2026-07-10.

Response

• x-request-id required - Request identifier. Log this value when contacting support.
• mymolecules-api-version required 2026-07-10 - The API contract version used for the response.
• x-ratelimit-limit optional - Quota limit for the current key and window when quota data is available.
• x-ratelimit-remaining optional - Remaining requests in the current quota window when quota data is available.
• x-ratelimit-reset optional - ISO timestamp for the current quota window reset when quota data is available.
• retry-after optional - Seconds to wait before retrying when the request is rate-limited or temporarily unavailable.

Inputs

• Required q query parameter with the compound name to resolve

Returns

• status: resolved with compound_id and canonical_name
• status: needs_clarification with reason

Error codes

• missing_api_key
• invalid_api_key
• scope_not_allowed
• quota_exceeded
• rate_limited
• invalid_json
• invalid_request
• invalid_request_shape
• too_many_options
• input_too_large
• user_context_not_allowed
• detect_signals_not_allowed
• validation_error
• method_not_allowed
• unsupported_api_version
• job_not_found
• backlog_high
• service_unavailable
• upstream_timeout
• upstream_error
• internal_error

Request details

• An exact name or ID match may resolve immediately; otherwise the endpoint evaluates similar candidates.
• This endpoint returns one resolution, not a paginated list. An empty q is invalid.

Response details

• This is a synchronous GET endpoint.
• compound_id is a numeric string; pass it in Decode compound_identifier_ids as a string or integer.
• needs_clarification means the query was ambiguous, insufficiently confident or unavailable; no ID is returned.

Operational notes

• Requires x-api-key with the edge:get_decode_compound_id scope.
• Usage is counted and rate-limit headers are returned when quota data is available.
• This endpoint requires its own scope, separate from the Decode tier scopes.

Examples

GET /functions/v1/get_decode_compound_id?q=caffeine

{
  "data": {
    "status": "resolved",
    "compound_id": "2987",
    "canonical_name": "caffeine"
  },
  "meta": {
    "request_id": "req_...",
    "api_version": "2026-07-10"
  }
}

Code examples

curl 'https://api.mymolecules.de/functions/v1/get_decode_compound_id?q=caffeine' \
  -H "x-api-key: $MYMOLECULES_API_KEY" \
  -H 'mymolecules-api-version: 2026-07-10'