> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oqoqo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalog, resources, and uploads tools

> MCP tools for searching the project catalog, browsing GitHub, authoring tasks, tools, and treatments, uploading archives, and deleting resources.

Search and manage the project's [tasks](https://docs.oqoqo.ai/experiments/tasks.md), [files and machines](https://docs.oqoqo.ai/experiments/machines-and-files.md), [tools](https://docs.oqoqo.ai/experiments/tools.md), and [treatments](https://docs.oqoqo.ai/experiments/treatments.md).

* **Badges** are explained under [Approvals](https://docs.oqoqo.ai/mcp-server/overview.md#approvals).
* **`project_id`** is optional on most tools; without it, the server picks a project for that call only ([Projects](https://docs.oqoqo.ai/mcp-server/overview.md#projects)).
* **`expected_organization_id`** is an optional string on every write tool, omitted from parameter tables; pass `organization.id` from [`get_identity`](https://docs.oqoqo.ai/mcp-server/identity-and-projects#get_identity) ([Organization check](https://docs.oqoqo.ai/mcp-server/overview.md#organization-check)).
* **`limit`** values above a tool's maximum are capped, not refused.

## Tools

### inspect\_catalog

**Search the project catalog.** Lists the project's tasks, files, machines, tools, treatments, and agents, in a fixed order, each with its tags. `total` and `kindCounts` cover every match, not just the page.

Read-only · CLI: [`oqoqo catalog list`](https://docs.oqoqo.ai/cli/catalog#oqoqo-catalog-list)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `kinds` | array of `task`, `file`, `machine`, `skill`, `mcp`, `cli`, `sdk`, `treatment`, `agent` | No | Only these kinds. |
| `query` | string | No | Text to match. |
| `projection` | `compact`, `full` | No | `compact` (default) is for browsing. `full` adds what a change needs, such as each record's key and `updatedAt`, an agent's configuration revisions, and `turnsOffMcpTools`: whether the agent can run a treatment that turns MCP tools off. |
| `tags` | array of strings | No | Only records with any of these tags, by name or `tag_` ID. 1 to 20 tags. |
| `untagged` | boolean | No | `true`: only untagged records. With `tags`: those tags or none. |
| `limit` | integer | No | Results per page, up to 500 (default 100). |
| `cursor` | string | No | The `nextCursor` from the previous page. |

**Result fields**

`items`, `total`, `kindCounts`, and `page` (`requestedLimit`, `returnedCount`, `hasMore`, and `nextCursor`). Each item lists its tags. An agent item's `id` is its `agm_` ID, which a launch plan's `agentSelections` names. With `projection: "full"`, an MCP server's `facts.toolCount` is the number of tools its latest version listed at its last check, or `null` until a check lists them.

### browse\_github\_source

**Browse public GitHub repositories.** Finds a public github.com repository, ref, and path to import as a file or skill, and saves nothing. Pass the result to `author_resource` as `source.repository`, `source.ref`, and `source.path`.

Read-only · CLI: [`oqoqo github browse`](https://docs.oqoqo.ai/cli/catalog#oqoqo-github-browse)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `view` | `repositories`, `refs`, `paths` | Yes | `repositories`: matches for `query`. `refs`: branches and tags of `repository`. `paths`: folders and files, or skill folders, at one commit. |
| `repository` | string | With `refs` and `paths` | A public `owner/repository`, or a repository, tree, blob, or commit URL. Up to 500 characters. |
| `ref` | string | No | With `paths`: a branch, tag, or commit. Omit it to use the ref in the URL or the default branch. |
| `kind` | `skill`, `file` | With `paths` | What the import creates. `skill` lists skill folders with their skill counts; `file` lists folders and files. |
| `query` | string | With `repositories` | A name, `owner/name`, `owner/`, or GitHub URL, up to 200 characters. With `refs`: a name prefix. With `paths`: text the path contains. |
| `limit` | integer | No | Default and maximum: `repositories` 10 and 30, `refs` 100 and 200, `paths` 100 and 1,000. |

When `truncated` is true, narrow `query`. A URL result also returns its ref and path.

### inspect\_resource

**Get a resource and its versions.** Returns one record's details, direct dependencies, and a page of version history.

Read-only · CLI: [`oqoqo resources inspect`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-inspect)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `request.kind` | `task`, `file`, `machine`, `skill`, `mcp`, `cli`, `sdk`, `treatment` | Yes | The kind of record. |
| `request.id` | string | Yes | The record's ID or key. |
| `request.view` | `summary`, `versions`, `dependencies`, `definition` | No | What to return. Default `summary`. |
| `request.version` | integer | No | One version. |
| `request.beforeVersion` | integer | No | Continue version history from `nextBeforeVersion` while `hasMore` is true. |
| `request.versionLimit` | integer | No | Versions per page, up to 100 (default 50). |
| `request.cursor` | string | No | The `nextCursor` from the previous page of a list view. |
| `request.limit` | integer | No | Results per page in a list view, up to 500 (default 100). |
| `request.offset` | integer | No | With `definition`: continue from `content.nextOffsetBytes` until `content.eof` (default 0). |
| `request.limitBytes` | integer | No | Bytes per page, up to 12,288 (default 12,288). |

For a file or skill imported from GitHub, the `definition` view has `sourceAction`: the link (`href`) and the `repository` as `owner/name`, `ref`, `path`, and `commitSha` of the saved snapshot. `ref` is null when the import named a commit, `path` is null for a whole repository, and `sourceAction` is null for an upload ([See where an import came from](https://docs.oqoqo.ai/experiments/tools.md#see-where-an-import-came-from)).

A machine's `definition` view adds `variableOverrides`: machine variables that a CLI or SDK in the project also sets, with those `tools` and a `note`. In that tool's treatments, the tool's value wins ([When a tool sets the same name](https://docs.oqoqo.ai/experiments/machines-and-files.md#when-two-places-set-the-same-variable)).

### inspect\_resource\_impact

**Check what depends on a resource.** Shows the tasks and treatments that use a record directly, and whether it is managed or pinned. Call it before a change.

Read-only · CLI: [`oqoqo resources impact`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-impact)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `request.kind` | `task`, `file`, `machine`, `skill`, `mcp`, `cli`, `sdk`, `treatment` | Yes | The kind of record. |
| `request.id` | string | Yes | The record's ID or key. |

### author\_resource

**Create or update a resource.** Creates or updates a task, file, machine, tool, or treatment, with the dashboard's rules. The tool's schema has the exact definition fields and limits.

Changes data · CLI: [`oqoqo resources apply`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-apply)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `operation` | object | Yes | One create or update. Its fields depend on `action` and `kind`, as below. |

Fields of `operation`:

| Field | Applies to | Description |
| - | - | - |
| `action` | All | `create` or `update`. |
| `kind` | All | `task`, `file`, `machine`, `skill`, `mcp`, `cli`, `sdk`, or `treatment`. |
| `mutationAttemptId` | All | Required. An ID you choose (1 to 100 characters), so that a retry doesn't repeat the change. Use a new one for each change. |
| `targetKey`, `expectedUpdatedAt` | Updates | Required, from `inspect_catalog` with `projection: "full"`. `targetKey` is the record's key; a CLI or SDK also accepts its public ID. |
| `versionId`, `version` | Task updates | Required on a task update: the version you read. |
| `name`, `instructionsMarkdown`, `environmentId` | Tasks | Required on a task create. `environmentId` is the machine's `env_` ID, from `inspect_catalog` with `kinds: ["machine"]`. |
| `rubric` | Tasks | The task's criteria and how they decide a pass. See the rubric paragraph below the table. |
| `assetAttachments` | Tasks | Files to attach, each with `projectAssetId` and `mountPath` (relative to the agent's working directory). Refer to each `mountPath` in the instructions. |
| `name`, `description`, `definition` | Machines, MCP servers, CLIs, SDKs | `name` and `definition` are required on a create. |
| `name`, `description`, `skillVersionIds`, `mcpServerVersionIds`, `cliVersionIds`, `sdkVersionIds` | Treatments | `name` is required on a create. The version ID lists name the treatment's tools; on an update, pass all four arrays (sending `[]` for empty lists). |
| `disabledMcpTools` | Treatments | [MCP tools to turn off](https://docs.oqoqo.ai/experiments/treatments.md#turn-off-mcp-tools): a list of `mcpServerVersionId` and `tools`, using names whose `canTurnOff` is true in `list_mcp_server_tools`. On an update, omit it to keep the current choices; sending it replaces them, and `[]` turns every tool back on. |
| `source` | Files, skills | A public GitHub source: `kind: "github"`, `repository`, and optional `ref` and `path`. Send only `source` for `file` and `skill` (without `name` or `description`). |

Unknown targets return `resource_not_found`, read-only records return `resource_read_only`, and a stale `expectedUpdatedAt` returns `resource_revision_conflict`.

* **Rubric:** a rubric has `schemaVersion: 1` and up to 100 `criteria`, each with `index` and `text`. Criteria use **Yes / no** by default, and Advanced mode adds fields such as `type`, `negate`, and `aggregation` ([Tasks and rubrics](https://docs.oqoqo.ai/experiments/tasks.md)).
* **Shape:** follow the branch for your `action` and `kind` exactly. Don't copy catalog-only fields such as `id`, `key`, `version`, or `versionId` into a branch that doesn't take them. An exact retry returns the first result, and a stale `expectedUpdatedAt` returns `resource_revision_conflict`.
* **GitHub source:** a GitHub source saves a snapshot at the resolved commit. Later GitHub changes apply only when you call `manage_resource` with `sync_github`. Omit `ref` for the default branch and `path` for the whole repository. A whole-repository skill import finds every `SKILL.md` at any depth and names each skill by the `name` in its `SKILL.md` ([Skills](https://docs.oqoqo.ai/experiments/tools.md#skills)). For local archives and task imports, use `create_upload`.
* **Secrets:** a definition names the environment variables and headers it needs, never their values. A value in an argument returns `secure_input_requires_web`, and the saved record returns the dashboard link where a person enters each value.

**Result fields**

| Field | Meaning |
| - | - |
| `action`, `status`, `message` | What the call did, as below |
| `resources` | Each resource's `kind`, `id`, `key`, `name`, `versionId`, `version`, `contentHash`, `dashboardUrl`, and `setupUrl` when a value is missing. A task's `versionId` is the `tskver_` ID that a launch plan needs. A treatment's `versionId` is `null`, and its `trt_` ID is in `id`. |

| `status` | Meaning |
| - | - |
| `created`, `updated`, `renamed`, `unchanged` | Oqoqo created, updated, or renamed the resource, or found nothing to change. |
| `matched_existing` | A treatment with the same tools exists. It is returned and nothing is saved. |
| `name_conflict` | Another treatment has that name. It is returned and nothing is saved. |

Every project already has the **Raw Agent** treatment for a baseline.

### bulk\_author\_resources

**Create or update many resources.** Applies up to 20 `author_resource` operations in order, each with its own `mutationAttemptId` and revision.

Changes data · CLI: [`oqoqo resources bulk-apply`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-bulk-apply)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `request.operations` | array of objects | Yes | 1 to 20 operations, each shaped like the `operation` of [`author_resource`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#author_resource). |

On a failure, the result keeps the completed entries and gives `failedIndex`, `failedMutationAttemptId`, the error, and `notStartedCount`. Fix the failed operation and resend the whole batch: completed attempt IDs return their first result. For archives, use `create_upload`.

### manage\_resource

**Set official versions and defaults, or sync from GitHub.** Sets or clears a tool's official version or the default machine, refreshes a file or skill from GitHub, or moves a treatment to its tools' current versions.

Changes data · CLI: [`oqoqo resources lifecycle`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-lifecycle)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `operation` | object | Yes | One change, as below. Every operation takes `action`, `kind`, `id`, `mutationAttemptId`, and `expectedUpdatedAt` from `inspect_catalog` with `projection: "full"`. |

| `action` | `kind` | Also takes |
| - | - | - |
| `set_official` | `skill`, `mcp`, `cli`, `sdk` | `versionId`: the version to make official |
| `clear_official` | `skill`, `mcp`, `cli`, `sdk` | |
| `set_default`, `clear_default` | `machine` | |
| `sync_github` | `file`, `skill` | |
| `update_members_to_current` | `treatment` | |

`sync_github` saves a new snapshot only when the selected content changed. Past runs keep their snapshots.

### download\_resource\_archive

**Download a file or skill archive.** Returns the ZIP as base64, with its size and SHA-256. Archives over 8 MB download from the record's dashboard page.

Read-only · CLI: [`oqoqo resources archive`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-archive)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `request.kind` | `file`, `skill` | Yes | The kind of record. |
| `request.id` | string | Yes | The record's ID or key. |
| `request.version` | integer | No | A skill version. Omit it to read the latest or official version. |
| `request.offset` | integer | No | Continue from `nextOffset` until `eof` (default 0). |
| `request.limitBytes` | integer | No | Bytes per call, up to 12,288 (default 12,288). |

### create\_upload

**Start an archive upload.** Creates or replaces a file, creates or versions skills, or imports tasks from an archive. Never put archive bytes or base64 in arguments.

Changes data · CLI: [`oqoqo uploads create`](https://docs.oqoqo.ai/cli/catalog#oqoqo-uploads-create)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `operation` | object | Yes | What the completed upload does, as below. |
| `file` | object | No | The local archive: `fileName` (`.zip`, or `.skill` for skills; at most 255 bytes), exact `byteSize`, and lowercase hex `sha256`. Omit it when a person picks the archive in a browser. |

| `operation.kind` | `operation.action` | Also takes |
| - | - | - |
| `file` | `create` | Optional `name` (1 to 120 characters; derived from the archive name when omitted) and `description` (up to 2,000 characters) |
| `file` | `update` | `targetKey`, `expectedUpdatedAt`, and `name` (1 to 120 characters); optional `description` (up to 2,000 characters) |
| `skill` | `create` | Optional `markOfficial`: make every imported skill version official |
| `skill` | `update` | `targetKey` and `expectedUpdatedAt`; optional `markOfficial` |
| `task` | `import` | Nothing. The archive is an `oqoqo-task-import` ZIP. |

Choose one path:

1. **You can read the archive.** Send `file` (`fileName` 1 to 255 bytes ending in `.zip` or `.skill`, exact `byteSize`, and 64-character lowercase hex `sha256`), then PUT the raw bytes to `transfer.url` with `curl -X PUT --upload-file <archive>` and one `-H` per entry in `transfer.headers`. Never send Oqoqo credentials there. Then call `complete_upload`.
2. **A person picks the archive.** Omit `file`. The person opens `upload.uploadUrl` where they're signed in (hosts that support URL requests show it), and that page completes the upload. Poll `get_upload`.

Pass `upload.projectId` as `project_id` to the other upload tools. Each upload expires at `upload.expiresAt`, and an abandoned upload creates nothing. A stale `expectedUpdatedAt` fails at once with `resource_revision_conflict`.

| Archive | Size | Expanded content | Entries |
| - | - | - | - |
| Files and task imports | Up to 512 MiB | Up to 512 MiB | Up to 65,535 files and folders |
| Skills | Up to 256 MiB | Up to 256 MiB | Up to 65,535 files and folders |

A task import creates at most 50 tasks.

### get\_upload

**Get an archive upload.** Returns an upload's status, declared file, `uploadUrl`, `lastError`, and, once completed, its records in `result`. Only its creator can read it.

Read-only · CLI: [`oqoqo uploads get`](https://docs.oqoqo.ai/cli/catalog#oqoqo-uploads-get)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The upload's project. Pass `upload.projectId`. |
| `upload_id` | string | Yes | The `upl_` ID from `create_upload`. |

Poll while `status` is `awaiting_upload`. If it has `lastError`, upload a corrected archive. `completed`, `failed`, `cancelled`, and `expired` are final.

### complete\_upload

**Complete an archive upload.** Checks the archive against the declared size and SHA-256, validates it, and applies the operation once, including any file replacement or official skill version change.

Destructive · CLI: [`oqoqo uploads complete`](https://docs.oqoqo.ai/cli/catalog#oqoqo-uploads-complete)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The upload's project. Pass `upload.projectId`. |
| `upload_id` | string | Yes | The `upl_` ID, also the retry key. |

The call returns `upload_not_ready` until the bytes arrive. An archive error keeps the upload `awaiting_upload` with `lastError`. An operation error, such as a stale revision (`resource_revision_conflict`) or a deleted target (`resource_not_found`), ends the upload as `failed`.

### cancel\_upload

**Cancel an archive upload.** Cancels an unfinished upload and deletes its archive.

Destructive · CLI: [`oqoqo uploads cancel`](https://docs.oqoqo.ai/cli/catalog#oqoqo-uploads-cancel)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The upload's project. Pass `upload.projectId`. |
| `upload_id` | string | Yes | The `upl_` ID. |

Cancelling again returns the cancelled upload. A completed upload can't be cancelled, so change or delete its records instead.

### preview\_delete\_resources

**Preview resource deletion.** Shows what deleting the records removes or cancels (related experiments, runs, Evals, and stored files) and what blocks it.

Read-only · CLI: [`oqoqo resources delete --dry-run`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-delete)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `targets` | array of objects | Yes | 1 to 100 records. Each has `resourceType` and either `id` or `key` (not both; `file`, `machine`, and `experiment` require a public `id`), plus `version` when deleting a `*_version` without a `*_ver_` ID (other types omit `version`). |

`resourceType` is `task`, `task_version`, `skill`, `skill_version`, `file`, `machine`, `mcp_server`, `mcp_server_version`, `cli`, `cli_version`, `sdk`, `sdk_version`, `treatment`, or `experiment`.

**Result fields**

| Field | Meaning |
| - | - |
| `plan.summary` | Counts of targets, nodes, stored files, active runs, and blocked items (`blockedCount`) |
| `plan.nodes`, `plan.nodesTruncated` | What the deletion removes, cancels, or is blocked by, up to 500 items. An experiment's own runs read **Experiment runs**. |
| `plan.schedules` | The [schedules](https://docs.oqoqo.ai/experiments/schedules.md) that the deletion deletes, with their experiment |
| `plan.pausedSchedules` | The active schedules that it pauses because their experiment uses what it deletes. Each needs an edit before it can launch again. |
| `planHash` | The value to pass as `plan_hash` to `delete_resources` |

Show the plan to the person, including each schedule, before you call `delete_resources`.

### delete\_resources

**Permanently delete resources.** Deletes experiments, tasks, files, machines, tools, or treatments (or one version of a task or tool), with the experiments, runs, Evals, and Insights that depend on them, after cancelling active runs. Schedules of a deleted experiment are deleted; schedules whose experiment uses what it deletes are paused.

Destructive · Irreversible · CLI: [`oqoqo resources delete`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-delete)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `targets` | array of objects | Yes | 1 to 100 records, as in [`preview_delete_resources`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#preview_delete_resources). |
| `attempt_id` | string | Yes | An ID you choose, so that a retry doesn't repeat the change. It has 16 to 100 characters. |
| `plan_hash` | string | No | `planHash` from `preview_delete_resources`. If the plan changed, the call returns `resource_deletion_plan_changed` and deletes nothing. |

Blocked items return `resource_deletion_blocked`. Otherwise the deletion starts in this call, returning `job.deletionId`, and you poll `get_resource_deletion` until its status is final.

### get\_resource\_deletion

**Get resource deletion status.** Returns the status of a deletion from `delete_resources`.

Read-only · CLI: [`oqoqo deletions status`](https://docs.oqoqo.ai/cli/catalog#oqoqo-deletions-status)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project_id` | string | No | The `prj_` project. |
| `deletion_id` | string | Yes | The `del_` ID. |

Poll while the status is `preview_ready`, `queued`, or `deleting`. These statuses are final: `completed`, `failed`, `failed_to_start`, `needs_attention`, and `cancelled_before_start`. Any other status reads `unknown`.

## Related

> [card] [Experiments tools](https://docs.oqoqo.ai/mcp-server/experiments.md)
>
> Preflight, launch, watch, and publish experiments.

> [card] [oqoqo catalog, resources, and uploads](https://docs.oqoqo.ai/cli/catalog.md)
>
> The matching CLI commands and JSON schemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.