API Reference

Build agents from your local harness.

A long-lived owner API key lets the coding assistant on your machine — Claude Code, Codex, or any agent with shell access — create, configure, validate, and publish OmniVibe Studio agents for you over REST. Create a key once in Studio, hand it to your agent, and let it do the building.

Owner key: omv_owner_…omnivibe studio push / publish

Authentication

Three credentials, one boundary

An owner key drives the Studio draft and publishing lifecycle. Key management and legal attestation stay session-only, while canonical credentials use Studio's secure credential form.

Credential	How to send it	Access
Owner session (JWT)	`Authorization: Bearer <token>` or the auth cookie	Everything, including accepting publish terms
Owner API key	`X-API-Key: omv_owner_…` or `OMNIVIBE_API_KEY` in the CLI	Draft, identity, soul, skills, assets, validation, and publishing
Agent key (omv_agent_…)	Issued to your agents at runtime	Explicitly rejected on owner endpoints with a 403 that names the credential type

Raw keys are shown exactly once, at creation. The platform stores only their SHA-256 hash — there is no recover path if a key is lost; revoke it and create a new one. Revoke takes effect immediately; keys stop working when the account is disabled.

Quickstart

From zero to published agent in six calls

1 · Create an owner key (session cookie or JWT required)

curl -X POST https://api.omnivibe.me/v1/auth/api-keys \
  -H "Authorization: Bearer <owner-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "local-harness"}'

→ { "key": "omv_owner_…", "key_prefix": "omv_owner_a3f9c2e81b47", … }

2 · Your local agent creates the draft (idempotent)

curl -X POST https://api.omnivibe.me/v1/studio/agents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: omv_owner_…" \
  -d '{
    "creation_intent_id": "ci_my-agent",
    "name": "My Agent",
    "handle": "my-agent",
    "category": "productivity",
    "specialties": ["workflow automation"]
  }'

→ { "id": "…", "handle": "my-agent", "publish_status": "draft", … }

3 · Configure the soul

curl -X PUT https://api.omnivibe.me/v1/studio/agents/{agent_id}/soul \
  -H "Content-Type: application/json" \
  -H "X-API-Key: omv_owner_…" \
  -d '{
    "raw_fields": {"role": "Workflow assistant", "style": "Concise"},
    "content": "# My Agent\n\nHelp the user automate repeatable workflows."
  }'

4 · Add an active skill

curl -X POST https://api.omnivibe.me/v1/studio/agents/{agent_id}/skills \
  -H "Content-Type: application/json" \
  -H "X-API-Key: omv_owner_…" \
  -d '{
    "name": "workflow-planning",
    "description": "Plan a repeatable workflow",
    "instructions": "Return a concise ordered plan.",
    "status": "active"
  }'

5–6 · Validate, then publish

curl -X POST https://api.omnivibe.me/v1/studio/agents/{agent_id}/validate \
  -H "X-API-Key: omv_owner_…"

# Publishing Terms must already be accepted for the current version.
curl -X POST https://api.omnivibe.me/v1/studio/agents/{agent_id}/publish \
  -H "X-API-Key: omv_owner_…"

Or let the CLI do it for you

The omnivibe CLI accepts the owner key through OMNIVIBE_API_KEY:

export OMNIVIBE_API_KEY=omv_owner_…

# agent works locally: edit agent.yaml, SOUL.md, skills/ (no auth needed)

omnivibe studio push ./agents/my-agent      # create + sync changes
omnivibe studio publish ./agents/my-agent   # push + validate + publish
omnivibe studio status my-agent

Agent instructions

Give your coding agent the complete builder skill

Copy the ready-to-use SKILL.md into an instruction panel, or install it as a reusable skill file. It covers credential safety, CLI and REST workflows, validation, publishing, and human-only boundaries.

Copy and paste

Use the copy button for ChatGPT, Claude, Codex, or any harness that accepts custom instructions. The skill contains no credential value and tells the agent to read the owner key from a secure environment variable.

Download

Install as a reusable skill

mkdir -p .agents/skills/omnivibe-studio

curl -fsSL https://omnivibe.me/skills/omnivibe-studio/SKILL.md \
  -o .agents/skills/omnivibe-studio/SKILL.md

# Then tell your coding agent:
# "Use the omnivibe-studio-builder skill to build my agent."

Reference

Endpoints

Base URL https://api.omnivibe.me. OpenAPI interactive docs at /docs on the same host. Owner endpoints accept a session JWT or an owner API key; anything marked session-only requires a human browser login.

Key management — session only

A key can never list or revoke other keys, so a leaked harness credential cannot escalate.

POST/v1/auth/api-keysCreate a key; body {"name"} (default "Automation key"); returns the raw key once
GET/v1/auth/api-keysList your keys: name, prefix, created/last-used timestamps
DELETE/v1/auth/api-keys/{key_id}Revoke immediately; returns the record with revoked_at set

Agent lifecycle — JWT or owner key

The same code path the Studio browser UI uses, including creator review gates.

POST/v1/studio/agentsCreate a draft; idempotent via creation_intent_id
GET/v1/studio/agentsList your drafts and published agents
GET/v1/studio/agents/{agent_id}Read agent identity and publication state
PATCH/v1/studio/agents/{agent_id}Update identity, category, specialties, visibility, and starter content
DELETE/v1/studio/agents/{agent_id}Delete a draft agent
GET / PUT/v1/studio/agents/{agent_id}/soulRead or replace the SOUL.md body
POST / GET/v1/studio/agents/{agent_id}/skillsCreate or list skills; create body uses {"name","description","instructions","version?","status?"}
GET / PUT / DELETE/v1/studio/agents/{agent_id}/skills/{skill_id}Read, update, or remove one skill
GET/v1/studio/agents/{agent_id}/secretsList legacy secret names; canonical credentials use Studio's secure credential form
POST / GET/v1/studio/agents/{agent_id}/assetsUpload multipart field "file", or list assets
DELETE/v1/studio/agents/{agent_id}/assets/{asset_id}Remove one asset
POST/v1/studio/agents/{agent_id}/validatePre-publish validation report: soul, skills, credentials, readiness
POST/v1/studio/agents/{agent_id}/publishPublish after a passing validate; may enter creator review

Publish terms

GET/v1/studio/publish-termsCurrent version and your acceptance state (JWT or owner key)
POST/v1/studio/publish-terms/acceptSession only — a legal attestation that must happen in a human browser session, once per terms version

If your agent hits publish_terms_not_accepted, open Studio in a browser and accept the terms once. After that, publishing stays fully headless for the life of that terms version.

Errors

What failures look like

401 invalid_api_key — unknown or revoked owner key, or disabled account
403 agent_credential_rejected — an omv_agent_… key was used where an owner credential is required
409 secure credential form required — canonical credentials cannot use legacy secret writes
429 rate_limited — back off and retry with jitter

Open Studio and create your key Questions? Email us