canonical: https://jentic.com/apis/arvados.org/arvados

# Arvados API

Jentic publishes the only available OpenAPI specification for Arvados API, keeping it validated and agent-ready. Arvados is an open-source platform for managing and analysing large-scale biomedical data. Its REST API spans 104 endpoints across collections, containers, container requests, workflows, groups, users, links, logs, virtual machines, keep services, authorized keys, computed permissions, vocabularies, and credentials. Use it to upload datasets, kick off containerised analyses, manage compute groups and access, and read execution logs and provenance.

## For AI agents

Run and manage Arvados biomedical compute: collections, container requests, workflows, groups, users, and access controls on an Arvados cluster.

## Scope

Does not handle clinical EHR data, billing, or external data warehouses - use for managing Arvados collections, container requests, workflows, and access only.

## Capabilities

- Create and manage data collections, including provenance and trash/untrash operations
- Submit container requests and inspect their containers and logs
- Run and manage Arvados workflows on a cluster
- Manage groups, users, and authorized SSH keys for cluster access
- Issue and manage API client authorizations and credentials
- Read computed permissions to audit who can access which collections
- Manage virtual machines, keep services, and cluster configs

## Use cases

### Genomic Pipeline Execution

Submit genomic analysis pipelines to an Arvados cluster by creating an input collection, posting a container request that references the workflow, and polling the resulting container for completion. /arvados/v1/collections, /arvados/v1/container_requests, and /arvados/v1/containers expose the data, request, and execution layers needed end to end.

Example prompt: Create a collection containing the input FASTQ files via /arvados/v1/collections, then POST /arvados/v1/container_requests referencing the GATK workflow and the new collection's uuid

### Cluster Access Management

Manage who can access an Arvados cluster by provisioning users in groups, registering authorized SSH keys, and issuing API client authorizations. /arvados/v1/users, /arvados/v1/groups, /arvados/v1/authorized_keys, and /arvados/v1/api_client_authorizations cover the typical onboarding flow for a new researcher.

Example prompt: Add user 'researcher@uni.edu' to group 'lab-2026', register their SSH key via /arvados/v1/authorized_keys, and create an API client authorization for their pipelines

### Provenance and Audit Reporting

Build provenance and audit reports by reading /arvados/v1/collections/{uuid}/provenance, /arvados/v1/collections/{uuid}/used_by, /arvados/v1/logs, and /arvados/v1/computed_permissions. The combination tells you which collections fed into which analyses and who could access them - essential for biomedical compliance reviews.

Example prompt: For collection uuid 'abc-123', call /arvados/v1/collections/abc-123/provenance and /arvados/v1/collections/abc-123/used_by, then write the lineage graph to a CSV

### Storage Hygiene Workflow

Maintain storage hygiene on an Arvados cluster by listing collections, identifying ones older than a retention threshold, and trashing them via /arvados/v1/collections/{uuid}/trash. The /untrash counterpart provides safe recovery if a researcher requests it before garbage collection runs.

Example prompt: List collections modified more than 365 days ago, trash each via /arvados/v1/collections/{uuid}/trash, and write a recovery list of uuids in case any need /untrash

### Agent-Driven Analysis Submission via Jentic

Let a research assistant agent submit an analysis on a researcher's behalf. The agent searches Jentic for 'submit an Arvados container request', loads the schema for /arvados/v1/container_requests, and executes - without persisting the bearer token in the agent process.

Example prompt: Search Jentic for 'submit an Arvados container request', load the schema, and execute referencing workflow uuid 'wf-42' and input collection uuid 'col-99'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /arvados/v1/collections | List collections |
| GET | /arvados/v1/collections/{uuid}/provenance | Fetch a collection's provenance graph |
| GET | /arvados/v1/containers | List containers |
| GET | /arvados/v1/groups | List groups |
| GET | /arvados/v1/users | List users |
| GET | /arvados/v1/authorized_keys | List authorized SSH keys |
| GET | /arvados/v1/api_client_authorizations/current | Fetch the current API client authorization |
| GET | /arvados/v1/computed_permissions | Read computed permissions across the cluster |

## Key resources

- **Collections** — Create, list, fetch, trash, and inspect provenance of data collections
- **Container Requests** — Submit and manage requests to run containers on the cluster
- **Containers** — Inspect running and completed containers
- **Workflows** — Manage and run Arvados workflows
- **Groups and Users** — Manage user accounts and group membership
- **Authorized Keys and API Client Authorizations** — Manage SSH and API access credentials
- **Logs and Computed Permissions** — Read execution logs and audit computed permissions
- **Keep Services and Virtual Machines** — Manage cluster storage and compute resources

## Why Jentic

- **Setup:** Wiring Arvados by hand means handling its bearer auth against its cluster host and navigating over a hundred endpoints for collections, containers, and permissions. Through Jentic you install once, import the Arvados API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Arvados puts the resource uuid in the URL path (/arvados/v1/collections/{uuid}/provenance), so a rule can pin your agent to reads for one collection. You choose the operations it may call, so group or user management is not included unless you add it.
- **Credential handling:** Your Arvados bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list Arvados collections' or 'submit an Arvados container request', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without navigating the full reference.

## Related APIs

- **Kubernetes API** — Kubernetes is a general-purpose container orchestrator; Arvados is a domain-specific biomedical compute platform built on top of similar primitives
- **GitHub API** — GitHub hosts the workflow definitions (CWL/WDL) that Arvados runs
- **Snowflake API** — Snowflake stores downstream analytical tables produced from Arvados pipeline outputs

## FAQ

### Why is there no official OpenAPI spec for Arvados API?

Arvados publishes a Discovery Document rather than an OpenAPI specification. Jentic generates and maintains an OpenAPI spec so that AI agents and developers can call Arvados API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Arvados API use?

Arvados uses HTTP Bearer authentication. You pass an API token in the Authorization header. Tokens are managed via /arvados/v1/api_client_authorizations and the current token can be inspected via /arvados/v1/api_client_authorizations/current. Through Jentic, the token is stored encrypted in the vault and injected at execution.

### Can I submit a container request through the Arvados API?

Yes. POST /arvados/v1/container_requests creates a request to run a containerised analysis. The corresponding container can then be inspected via /arvados/v1/containers/{uuid} and its logs read from /arvados/v1/logs.

### What are the rate limits for the Arvados API?

Arvados clusters do not impose a fixed public per-second rate limit; throughput is bounded by cluster capacity and per-user quotas configured by the cluster admin. For automated pipelines, follow Arvados' guidance on bulk operations and prefer paginated reads over many small calls.

### How do I list my Arvados collections through Jentic?

Run pip install jentic, then search Jentic with 'list Arvados collections', load the schema for GET /arvados/v1/collections, and execute. The response is paginated; pass limit and offset to walk the full list.

### Can I trash and untrash collections through the API?

Yes. /arvados/v1/collections/{uuid}/trash moves a collection to trash and /arvados/v1/collections/{uuid}/untrash restores it. Final deletion happens after the cluster's configured trash lifetime expires.

### How do I audit who has access to a collection?

Use GET /arvados/v1/computed_permissions to read the computed permission graph; combine with /arvados/v1/groups and /arvados/v1/users to resolve names. This is the supported way to produce access-audit reports for biomedical compliance.

### Can I limit what my agent is allowed to do with the Arvados API?

Yes. Because you run Jentic One yourself, your own rules decide which Arvados operations and credentials the agent may use. Arvados puts the resource uuid in the URL path, such as /arvados/v1/collections/{uuid}/provenance, so a rule can pin the agent to reads for a single collection rather than the whole cluster. You pick the exact operations it may call, so user, group, and authorized-key management stay off limits unless you explicitly allow them.