ARAX query contract

Contents

• Service boundary
• Supported query shapes
• Validation
• Fixed operations
• Limits and retries
• Version and endpoint policy
• Excluded escape hatches

Service boundary

Use https://arax.transltr.io/api/arax/v1.4 by default. A networked command first retrieves /openapi.json, verifies an ARAX title and /query, and records the advertised ARAX and TRAPI versions. Normalization uses /entity; graph lookup uses /query.

Every normalization or graph request requires --acknowledge-public-query. This is an explicit acknowledgment that query and caller metadata may be visible through service facilities. The store=false operation reduces intentional response storage but is not a privacy guarantee.

Supported query shapes

One hop

Use two qnodes (n0, n1) and one qedge (e0). Require one category on each qnode, one to five predicates, and at least one pinned endpoint. Each qnode has at most one CURIE. Omit ids from an unpinned qnode.

Two hops

Use three qnodes (n0, n1, n2) and two qedges (e0, e1). Pin n0 and n2 with exactly one CURIE each. Type every qnode. Keep n1 unpinned. Each edge has one to five predicates.

For either shape, an edge may have zero to six qualifiers. Combine them in one qualifier_constraints entry containing one AND-conjoined qualifier_set. Omit the whole field when no qualifier is supplied. Do not repeat a qualifier type on the same edge.

Validation

CURIEs follow this conservative form:

^[A-Za-z][A-Za-z0-9._-]*:[^\s]+$

They must be no more than 200 characters and contain no controls, NUL, tabs, or newlines.

Categories, predicates, and qualifier types follow:

^biolink:[A-Za-z][A-Za-z0-9._-]*$

Provider identifiers are interpolated into an ARAXi action and therefore use the stricter form:

^infores:[A-Za-z0-9._-]+$

Do not maintain a local Biolink model or provider registry. Shape validation is local; ARAX remains the semantic authority. Reject duplicate predicates, qualifier types, provider IDs, and repeated scalar endpoint options.

Fixed operations

Lookup mode fixes the provider to infores:rtx-kg2. Federated mode requires two to five explicit, distinct provider identifiers and emits them in one list-valued kp= argument. Never omit kp and never generate duplicate kp= arguments.

One hop expands e0. Two-hop right-first expands e1 and then e0; left-first reverses only those two actions. Append exactly:

scoreless_resultify(ignore_edge_direction=true)
filter_results(action=limit_number_of_results,max_results=<1-50>,prune_kg=true)
return(response=true,store=false)

Each expansion fixes:

kp_timeout=30,return_minimal_metadata=false

Always send stream_progress: false and the constant submitter scientific-agent-skills-ncats-arax. Never put a user name, project name, or query term into the submitter or User-Agent.

Limits and retries

Retry OpenAPI and entity GET requests once after HTTP 429, 502, 503, 504, or a transport timeout. Honor Retry-After for at most 10 seconds; otherwise wait one second. Never retry POST /query. A failed POST may have been processed and must be rerun only by an explicit user decision.

Use these headers:

Accept: application/json
Accept-Encoding: identity
Content-Type: application/json        # POST only
User-Agent: scientific-agent-skills-ncats-arax/1.0

Version and endpoint policy

The tested target is ARAX 1.5.4 with TRAPI 1.5.0. Parse the common response fields for TRAPI 1.5 and 1.6, warning whenever the version is not the tested value. Refuse an unknown or missing TRAPI series unless --allow-untested-version is explicit. Record biolink_version from each query response rather than assuming it.

Accept only HTTPS base URLs without credentials, query strings, or fragments. Reject localhost and literal private, loopback, link-local, or reserved addresses. A URL other than the production base requires --allow-nonproduction-endpoint, must still identify ARAX through OpenAPI, and receives a warning. Reject cross-origin and protocol-downgrade redirects. Never fall back automatically to arax.ncats.io or another ARA.

Excluded escape hatches

Expose no raw JSON submission, query-file, generic node/edge list, workflow, operations, action, overlay, ranking, inference, creative-query, link-prediction, Pathfinder, ARS, all-provider, batching, stdin-list, cache, database, daemon, server, SDK, MCP, or third-hop option.

The offline summarizer validates the saved request against this same topology and operation contract. It refuses unsupported requests rather than becoming a back door for broader ARAX use.