- Badges are explained under Approvals.
project_idis optional on most tools; without it, the server picks a project for that call only (Projects).expected_organization_idis an optional string on every write tool, omitted from parameter tables; passorganization.idfromget_identity(Organization check).limitvalues 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
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 toauthor_resource as source.repository, source.ref, and source.path.
Read-only · CLI: oqoqo github browse
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
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).
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).
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
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
Fields of
operation:
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: 1and up to 100criteria, each withindexandtext. Criteria use Yes / no by default, and Advanced mode adds fields such astype,negate, andaggregation(Tasks and rubrics). - Shape: follow the branch for your
actionandkindexactly. Don’t copy catalog-only fields such asid,key,version, orversionIdinto a branch that doesn’t take them. An exact retry returns the first result, and a staleexpectedUpdatedAtreturnsresource_revision_conflict. - GitHub source: a GitHub source saves a snapshot at the resolved commit. Later GitHub changes apply only when you call
manage_resourcewithsync_github. Omitreffor the default branch andpathfor the whole repository. A whole-repository skill import finds everySKILL.mdat any depth and names each skill by thenamein itsSKILL.md(Skills). For local archives and task imports, usecreate_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.
Every project already has the Raw Agent treatment for a baseline.
bulk_author_resources
Create or update many resources. Applies up to 20author_resource operations in order, each with its own mutationAttemptId and revision.
Changes data · CLI: oqoqo resources bulk-apply
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
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
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
Choose one path:
- You can read the archive. Send
file(fileName1 to 255 bytes ending in.zipor.skill, exactbyteSize, and 64-character lowercase hexsha256), then PUT the raw bytes totransfer.urlwithcurl -X PUT --upload-file <archive>and one-Hper entry intransfer.headers. Never send Oqoqo credentials there. Then callcomplete_upload. - A person picks the archive. Omit
file. The person opensupload.uploadUrlwhere they’re signed in (hosts that support URL requests show it), and that page completes the upload. Pollget_upload.
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.
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
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
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
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
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
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
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 fromdelete_resources.
Read-only · CLI: oqoqo deletions status
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
Experiments tools
Preflight, launch, watch, and publish experiments.
oqoqo catalog, resources, and uploads
The matching CLI commands and JSON schemas.

