OSDU API

scripts/osdu.py calls the OSDU APIs of the environment the current kubectl context points at. It reads the base URL, service paths, and partitions from spi info --json and gets every token from spi token --json, so it holds no endpoint or credential logic of its own. Standard library only.

osdu() { uv run .github/skills/osdu-api/scripts/osdu.py "$@"; }

osdu connect                                  # read the environment, check the token
osdu call GET /api/legal/v1/legaltags
osdu call POST /api/search/v2/query -d '{"kind":"*:*:*:*","query":"*","limit":10}'
osdu services --probe                         # version and commit of each service
osdu disconnect                               # clear local state

connect is optional: call, services, and token connect on first use. Run it again after spi up changes the ingress address or the partitions. Point at another environment with uv run spi connect; state is kept per kubectl context.

Identities

Every command that sends a token takes --as, written after the subcommand. connect --as sets the default for later commands and drops every cached token; call --as overrides the default for one call.

Use me when the question is about a person's permissions. A person is a member only after spi users add:

uv run spi users add --me --role viewer       # viewer, editor, admin (default), ops
osdu connect --as me
osdu call GET /api/entitlements/v2/groups

Compare identities by repeating one call:

osdu call GET /api/legal/v1/legaltags --as member
osdu call GET /api/legal/v1/legaltags --as no-access

spi users add changes entitlements membership. Run it only when the user asks for a role change; reading with an identity never needs it.

Making calls

osdu call <METHOD> <PATH> [options]

The output is one JSON document: status, as, body, and a hint when a refusal has a known cause. An HTTP refusal exits 0 unless --fail is given; read status.

Environment values

Take these from the connect output; do not assume them.

• Partition. partition is the primary. An environment may declare more.
• ACL groups. <group>@<partition>.<entitlements_domain>, for example data.default.viewers@opendes.dataservices.energy.
• Legal tag. partitions.<name>.legal_tag is the tag seeded for sample data. It is empty until the legal init Job has succeeded.

Service paths

services prints the paths this environment publishes. Any path under the gateway works with call.

Every service except indexer-queue answers GET <base>/info; services --probe reports that one as no info endpoint.

Refusals

Script errors arrive on stderr as {"error": "..."} with exit 1:

Local state

~/.cache/spi/osdu-api-<context>.json (mode 0600 on Linux and macOS) holds the environment facts and the bearer tokens minted so far, each reused until two minutes before it expires. disconnect deletes it. Never print a token into a reply, an issue, or a PR; status shows callers and lifetimes without them.

References

• API reference: endpoints and request bodies per service
• Search patterns: query syntax, sorting, paging, indexing delay
• Record lifecycle: legal tag, create, read, update, delete