Import a genome over REST

Status

Needs an IntelliNix workspace with the genome flags on Workspace import routes under /genome. Preview, consent and undo with curl. Needs the agent_genome and genome_format flags and an administrator.
Not available yet Import through the public /genome/v1 API. The /genome/v1 import routes are not mounted. The public API can read, compile and export a genome, not import one.

Prerequisites

An IntelliNix workspace with agent_genome and genome_format on. Without them the routes answer 404 as if they did not exist.
An administrator account (the routes need the settings update permission).
Your API address as [YOUR-INTELLINIX-API] and a credential as [YOUR-API-KEY]. The snippets send it in the X-API-Key header. These routes use the web API's shared sign-in check, which also accepts an Authorization: Bearer token.
A file of at most 256 KB, and its checksum checked (install page).
For the agent route: the agent's id, as [AGENT-ID]. It is the agent's id, not its slug.

Not tested with an API key

The platform's own book describes these routes as web-app routes used with a session. The code accepts an API key through the same check, but no scope is checked on these routes, and they were not run with a key. If a key is refused, sign in and use a token.

The routes

Import routes
Method and path	What it does	Needs
`POST /genome/workspace/import/preview`	Preview an import into the workspace layers only.	agent_genome, genome_format, administrator
`POST /genome/agents/{agent_id}/import/preview`	Preview an import into one agent and the workspace layers. Optional query parameter team_id.	agent_genome, genome_format, administrator
`GET /genome/transfers/{transfer_id}`	Read one transfer: its status and its preview.	agent_genome, and genome_format or genome_reproduction, administrator
`POST /genome/transfers/{transfer_id}/consent`	Apply a previewed import.	as above
`POST /genome/transfers/{transfer_id}/undo`	Undo an applied import. Body: confirm_later_changes (true or false).	as above
`GET /genome/workspace/transfers`	List the workspace’s transfers, newest first (summaries only). Optional query parameter limit, 1 to 100.	as above

The exact calls

Send the file itself as the request body. Use --data-binary, not -d, so the file is sent as it is.

1. Preview

Writes only a transfer record. Nothing is applied.

Preview into the workspace layers bash

curl -sS -X POST '[YOUR-INTELLINIX-API]/genome/workspace/import/preview' \
  -H 'X-API-Key: [YOUR-API-KEY]' \
  -H 'Content-Type: application/json' \
  --data-binary '@my-genome.agf.json'

Preview into one agent and the workspace layers bash

curl -sS -X POST '[YOUR-INTELLINIX-API]/genome/agents/[AGENT-ID]/import/preview' \
  -H 'X-API-Key: [YOUR-API-KEY]' \
  -H 'Content-Type: application/json' \
  --data-binary '@my-genome.agf.json'

2. Read the answer, then apply

Copy the id from the answer into [TRANSFER-ID]. You can read the transfer again at any time.

Read a transfer bash

curl -sS '[YOUR-INTELLINIX-API]/genome/transfers/[TRANSFER-ID]' \
  -H 'X-API-Key: [YOUR-API-KEY]'

Apply the previewed import bash

curl -sS -X POST '[YOUR-INTELLINIX-API]/genome/transfers/[TRANSFER-ID]/consent' \
  -H 'X-API-Key: [YOUR-API-KEY]'

3. Undo

If lists changed after the import, the first undo answers 409 with code later_changes and a count, and writes nothing. Read it. To undo anyway, send the second form.

Undo bash

curl -sS -X POST '[YOUR-INTELLINIX-API]/genome/transfers/[TRANSFER-ID]/undo' \
  -H 'X-API-Key: [YOUR-API-KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"confirm_later_changes":false}'

Undo, after confirming the later changes bash

curl -sS -X POST '[YOUR-INTELLINIX-API]/genome/transfers/[TRANSFER-ID]/undo' \
  -H 'X-API-Key: [YOUR-API-KEY]' \
  -H 'Content-Type: application/json' \
  -d '{"confirm_later_changes":true}'

Expected results

Each step answers with the transfer. The fields are:

id and status. The status is previewed after the preview, applied after consent and undone after undo. Other values are applying, failed and expired.
created_at and expires_at. A preview expires 7 days after it was made.
target: agent_id and team_id.
counts: accepted, unchanged, skipped, rejected and germline_ignored.
genes, one row per gene considered; rejected and skipped, with a reason for each.
failure and rollback_pending, set only when an apply failed.

A rejected file answers with an error and leaves no record at all.

The public API cannot import

The public API under /genome/v1 is for agents that run outside IntelliNix. Its import routes are not mounted yet, so there is nothing to call. Use the routes above. What the public API does offer, with the scope the key needs:

Public API routes
Method and path	What it does	Key scope
`GET /genome/v1/agents/{slug}`	The composed genome of an agent.	`genome:read`
`POST /genome/v1/agents/{slug}/compile`	Compile the genome for a task.	`genome:read`
`POST /genome/v1/compiles/{compile_id}/finalize`	Strip the genome report from a model output.	`genome:read`
`POST /genome/v1/compiles/{compile_id}/outcome`	Record the outcome of a compile, once.	`genome:write`
`GET /genome/v1/agents/{slug}/export`	Export an agent’s genome as AGF. Administrators only.	`genome:read`

These need genome_public_api and agent_genome on, and a key that carries the scope explicitly. A key without a scopes field is refused (403). Asking for another workspace's agent answers 404.

Troubleshooting

HTTP answers from the import routes
Answer	What it means	What to do
401	The credentials were not accepted.	Check the key or token. A suspended or deleted account is refused with 403.
404	Not found. The same answer is used when a feature flag is off, when the agent or transfer id does not exist, and when it belongs to another workspace.	Ask a workspace administrator to turn on agent_genome and genome_format. Check the agent id or transfer id.
403	You are not allowed. The import routes need the settings update permission (an administrator). Applying a preview that holds personal-layer genes is allowed only for the administrator who made it.	Use an administrator account, and apply with the same account that made the preview.
422	The file was rejected, or nothing in it can be imported. The message starts with a code such as too_large, invalid_json, invalid_agf_version, unsupported_agf_major, invalid_document, forbidden_reference or digest_mismatch. Nothing is stored for a rejected file.	See the common problems table on the install page, then fix the file and preview again.
409	The step cannot happen now: the memory changed since the preview (stale), the preview is older than 7 days (expired), the transfer is not in a state that allows the step (invalid_transition, for example applying twice), or the memory changed while applying (conflict, and none of the import is kept).	Preview the file again, then apply.
409 on undo	Lists changed after the import. The answer has code later_changes and a count, and nothing is written.	Read the warning. To undo anyway, send the undo again with confirm_later_changes set to true.