API Reference

Agent Runtime

Personal Agent settings, files, skills, packages, and template versions.

Related In Learn

Agentic Runtimes

Choose a Personal Agent runtime and manage versioned instructions, packages, and shared files for each agent.

Manage the same Personal Agent configuration as the builder through the public API. Use workspace API keys or a Personal API Key with an authorized workspace selected.

Set data.agenticRuntime to basic or agentic using the Agent create/update endpoints. This selects the runtime for one agent. OpenCode is the default provider for workspaces without an existing provider configuration; legacy provider overrides are preserved. GET runtime returns the effective provider. OpenCode templates apply to the OpenCode provider.

For files, skills, and packages: read the current head revision, create an upload intent, upload the ZIP, stage it with the original expectedHeadRevision, then publish with that same revision. A failed validation leaves the active version unchanged. On a 409 conflict, reload before saving again.

Place instructions in AGENTS.md, OpenCode settings in opencode.json, skills beneath .opencode/skills/, and package settings in root agentic-runtime.environment.json. Package settings use {"schemaVersion":1,"packages":{"npm":{"is-number":"7.0.0"}}}. Include a matching resolved npm v3 lock at agentic-runtime.npm-lock.json. In a separate directory, create a package.json named pickaxe-agent-environment at version 1.0.0, with dependencies equal to the manifest’s packages.npm. Run npm install --package-lock-only --lockfile-version=3 --ignore-scripts --registry=https://registry.npmjs.org there and copy its package-lock.json into the runtime directory under the required name. Regenerate the lock when packages change. The API validates the archive with the worker’s package policy; it does not resolve packages. Restores preserve the original lock. Activation can return a new immutable version ID; use the returned ID for downloads and subsequent operations.

The existing Agent PATCH and build/apply endpoints keep prompt edits synchronized with versioned AGENTS.md for Personal Agents. Those edits activate a new file version atomically; concurrent publication returns 409. Switching a Basic agent back to Personal Agent mirrors its active AGENTS.md unless an explicit prompt is supplied, which updates the file. Basic prompts remain independent of saved runtime files. Pickaxe manages the primary model, provider credentials, and sandbox connection. Model selection stays in the Agent API; arbitrary upstream OpenCode configuration, plugins, and executable hooks are not supported.

Unstaged uploads expire after 24 hours. Staging preserves the editing revision and removes upload expiry. A stale staged draft cannot be rebased by supplying a newer revision at publication.

The shared-files switch is a separate live, owner-only setting. Template updates and restores do not reset it or delete saved files. Inactive versions normally remain available for 30 days; snapshot references retain their artifacts.

Publish a runtime ZIP

This Node.js example uses a prepared ZIP containing your runtime files. Set PICKAXE_TOKEN locally and replace the agent and workspace IDs.

import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";

const agentId = "MY_AGENT";
const root =
  "https://api.pickaxe.co/v1/studio/pickaxe/" +
  encodeURIComponent(agentId) +
  "/runtime";
async function api(suffix, method = "GET", body) {
  const response = await fetch(root + suffix, {
    method,
    headers: {
      Authorization: "Bearer " + process.env.PICKAXE_TOKEN,
      // Personal keys also need an authorized workspace selected:
      "X-Pickaxe-Workspace-Id": "YOUR_WORKSPACE_ID",
      ...(body ? { "Content-Type": "application/json" } : {}),
    },
    ...(body ? { body: JSON.stringify(body) } : {}),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(result.error);
  return result.data;
}

const current = await api("");
const bytes = await readFile("runtime.zip");
const intent = await api("/uploads", "POST", {
  fileName: "runtime.zip",
  size: bytes.length,
  archiveSha256: createHash("sha256").update(bytes).digest("hex"),
});
const form = new FormData();
for (const [key, value] of Object.entries(intent.upload.fields))
  form.append(key, value);
form.append(
  "file",
  new Blob([bytes], { type: "application/zip" }),
  "runtime.zip",
);
// Presigned storage requests use the form's credentials, without the Pickaxe token.
const upload = await fetch(intent.upload.url, { method: "POST", body: form });
if (!upload.ok) throw new Error("Runtime ZIP upload failed");
await api("/versions/" + intent.versionId + "/stage", "POST", {
  expectedHeadRevision: current.headRevision,
});
const published = await api(
  "/versions/" + intent.versionId + "/publish",
  "POST",
  {
    expectedHeadRevision: current.headRevision,
    agenticRuntime: "agentic",
  },
);
console.log(published);

Endpoints

GET /studio/pickaxe/<pickaxe_id>/runtime

Inspect the selected runtime, effective provider, active template, and current head revision. Workspace owners and editor members can access runtime templates; viewers cannot.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>/runtime

Request Fields

pickaxe_id (string, required): Pickaxe ID in the authenticated workspace; supplied in the URL.

Examples

curl -X GET 'https://api.pickaxe.co/v1/studio/pickaxe/MY_AGENT/runtime' \
-H 'Authorization: Bearer YOUR_API_TOKEN'

Response Shape

{
  "success": true,
  "data": {
    "pickaxeId": "MY_AGENT",
    "agenticRuntime": "agentic",
    "effectiveProvider": "opencode",
    "headRevision": 1,
    "template": {
      "versionId": "ocwv-YOUR_VERSION_ID",
      "version": 1,
      "status": "published",
      "digest": "ARCHIVE_SHA256",
      "files": [
        {
          "path": "AGENTS.md",
          "size": 100,
          "sha256": "FILE_SHA256"
        }
      ]
    }
  }
}

GET /studio/pickaxe/<pickaxe_id>/runtime/settings

Read the owner-only live shared-files setting. Missing legacy settings default to enabled. This controls identified-user files across conversations and scheduled runs, separately from User Memory.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>/runtime/settings

Request Fields

pickaxe_id (string, required): Pickaxe ID in the authenticated workspace; supplied in the URL.

Examples

curl -X GET 'https://api.pickaxe.co/v1/studio/pickaxe/MY_AGENT/runtime/settings' \
-H 'Authorization: Bearer YOUR_API_TOKEN'

Response Shape

{ "success": true, "data": { "sharedFilesEnabled": true } }

PATCH /studio/pickaxe/<pickaxe_id>/runtime/settings

Change the live shared-files setting with an expected previous value. Requires workspace owner access. A conflicting save returns 409. Disabling it retains existing files; template publications and restores leave it unchanged.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>/runtime/settings

Request Fields

pickaxe_id (string, required): Pickaxe ID in the authenticated workspace; supplied in the URL.
sharedFilesEnabled (boolean, required): The new shared-files setting.
expectedSharedFilesEnabled (boolean, required): The value read immediately before this change.

Examples

curl -X PATCH 'https://api.pickaxe.co/v1/studio/pickaxe/MY_AGENT/runtime/settings' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "sharedFilesEnabled": false,
  "expectedSharedFilesEnabled": true
}'

GET /studio/pickaxe/<pickaxe_id>/runtime/versions

List published templates, newest first. History can contain versions published by either the builder or the API.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>/runtime/versions

Request Fields

pickaxe_id (string, required): Pickaxe ID in the authenticated workspace; supplied in the URL.
skip (integer, optional): Number of versions to skip. Defaults to 0.
limit (integer, optional): Page size from 1 to 100. Defaults to 50.

Examples

curl -X GET 'https://api.pickaxe.co/v1/studio/pickaxe/MY_AGENT/runtime/versions' \
-H 'Authorization: Bearer YOUR_API_TOKEN'

POST /studio/pickaxe/<pickaxe_id>/runtime/uploads

Create an upload intent. POST the ZIP to data.upload.url with every field in data.upload.fields followed by a file form part. The upload URL expires after five minutes; the intent expires after 24 hours. Send Pickaxe credentials only to the Pickaxe API, not to the presigned storage URL.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>/runtime/uploads

Request Fields

pickaxe_id (string, required): Pickaxe ID in the authenticated workspace; supplied in the URL.
fileName (string, required): ZIP filename, at most 200 characters.
size (integer, required): Exact archive size in bytes, from 1 to 12,000,000.
archiveSha256 (string, required): 64-character SHA-256 of the exact uploaded bytes.

Examples

curl -X POST 'https://api.pickaxe.co/v1/studio/pickaxe/MY_AGENT/runtime/uploads' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "fileName": "runtime.zip",
  "size": 1234,
  "archiveSha256": "YOUR_64_CHARACTER_SHA256"
}'

GET /studio/pickaxe/<pickaxe_id>/runtime/versions/<version_id>

Read published version metadata or a staged version created by the authenticated editor. Versions are scoped to both workspace and agent.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>/runtime/versions/<version_id>

Request Fields

pickaxe_id (string, required): Pickaxe ID in the authenticated workspace; supplied in the URL.
version_id (string, required): The immutable ocwv- version ID, supplied in the URL.

Examples

curl -X GET 'https://api.pickaxe.co/v1/studio/pickaxe/MY_AGENT/runtime/versions/ocwv-YOUR_VERSION_ID' \
-H 'Authorization: Bearer YOUR_API_TOKEN'

GET /studio/pickaxe/<pickaxe_id>/runtime/versions/<version_id>/download

Return data.url, a five-minute download URL, and data.digest, the archive SHA-256. Verify the downloaded bytes before extracting them. Only staged and published versions can be downloaded.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>/runtime/versions/<version_id>/download

Request Fields

pickaxe_id (string, required): Pickaxe ID in the authenticated workspace; supplied in the URL.
version_id (string, required): The immutable ocwv- version ID, supplied in the URL.

Examples

curl -X GET 'https://api.pickaxe.co/v1/studio/pickaxe/MY_AGENT/runtime/versions/ocwv-YOUR_VERSION_ID/download' \
-H 'Authorization: Bearer YOUR_API_TOKEN'

POST /studio/pickaxe/<pickaxe_id>/runtime/versions/<version_id>/stage

Validate uploaded files, OpenCode settings, skills, and resolved npm package locks using the runtime worker policy. Package manifests with dependencies require a matching agentic-runtime.npm-lock.json; this endpoint does not resolve packages. Supply the head revision from when editing began. Staging saves that revision with the draft and removes upload expiry; it does not activate the template. Publishing a stale draft returns 409 even if a newer revision is supplied later. Limits: 12 MB ZIP, 25 MB expanded, 500 entries, and 12 path levels. Package versions must be exact; up to 20 direct npm packages are supported, with lifecycle scripts disabled. Validation errors identify the rejected file or setting where available.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>/runtime/versions/<version_id>/stage

Request Fields

pickaxe_id (string, required): Pickaxe ID in the authenticated workspace; supplied in the URL.
version_id (string, required): The immutable ocwv- version ID, supplied in the URL.
expectedHeadRevision (integer, required): The headRevision returned by GET runtime. Use 0 when no template is published. A competing publication returns 409 runtime_conflict.

Examples

curl -X POST 'https://api.pickaxe.co/v1/studio/pickaxe/MY_AGENT/runtime/versions/ocwv-YOUR_VERSION_ID/stage' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "expectedHeadRevision": 0
}'

POST /studio/pickaxe/<pickaxe_id>/runtime/versions/<version_id>/publish

Atomically activate a staged template, update the agent's version reference and mirrored AGENTS.md instructions, and request rollout to existing sessions on their next activity. Requires the same editing revision supplied when staging. Activation returns a published version ID that can differ from the staged ID; use the returned ID for downloads and local state. A retry of an already active publication does not create another version.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>/runtime/versions/<version_id>/publish

Request Fields

pickaxe_id (string, required): Pickaxe ID in the authenticated workspace; supplied in the URL.
version_id (string, required): The immutable ocwv- version ID, supplied in the URL.
expectedHeadRevision (integer, required): The headRevision returned by GET runtime. Use 0 when no template is published. A competing publication returns 409 runtime_conflict.
agenticRuntime ("basic" | "agentic", optional): Optionally change this agent's runtime in the same transaction as template activation. Omission preserves its current selection; null is invalid.

Examples

curl -X POST 'https://api.pickaxe.co/v1/studio/pickaxe/MY_AGENT/runtime/versions/ocwv-YOUR_VERSION_ID/publish' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "expectedHeadRevision": 0,
  "agenticRuntime": "agentic"
}'

POST /studio/pickaxe/<pickaxe_id>/runtime/versions/<version_id>/restore

Republish a historical template and its original package lock as a new version. Earlier history remains intact. Live shared-file settings and identified users' saved files are preserved. Read the current head revision before restoring. Restoring the already active source is an idempotent no-op.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>/runtime/versions/<version_id>/restore

Request Fields

pickaxe_id (string, required): Pickaxe ID in the authenticated workspace; supplied in the URL.
version_id (string, required): The immutable ocwv- version ID, supplied in the URL.
expectedHeadRevision (integer, required): The headRevision returned by GET runtime. Use 0 when no template is published. A competing publication returns 409 runtime_conflict.
agenticRuntime ("basic" | "agentic", optional): Optionally change this agent's runtime in the same transaction as template activation. Omission preserves its current selection; null is invalid.

Examples

curl -X POST 'https://api.pickaxe.co/v1/studio/pickaxe/MY_AGENT/runtime/versions/ocwv-YOUR_VERSION_ID/restore' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "expectedHeadRevision": 3
}'

Agent

Action