Skip to main content
Search and manage the project’s tasks, files and machines, tools, and treatments.
  • Badges are explained under Approvals.
  • project_id is optional on most tools; without it, the server picks a project for that call only (Projects).
  • expected_organization_id is an optional string on every write tool, omitted from parameter tables; pass organization.id from get_identity (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 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 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: 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).
  • 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). 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 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 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:
  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. 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 from delete_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.

Experiments tools

Preflight, launch, watch, and publish experiments.

oqoqo catalog, resources, and uploads

The matching CLI commands and JSON schemas.