API Reference

Authenticate and interact with the OneCLI API to manage agents, secrets, policy rules, and app connections programmatically.

The OneCLI API gives you programmatic access to manage your agents, secrets, policy rules, and app connections.

Base URL

Cloud

https://api.onecli.sh/v1

http://localhost:10254/v1

Authentication

All API endpoints require authentication. Include your API key as a Bearer token in the Authorization header:

curl https://api.onecli.sh/v1/agents \
  -H "Authorization: Bearer oc_your_api_key_here"

Getting your API key

1. Open the OneCLI dashboard
2. Go to Settings and copy your API key

API keys start with oc_ and are scoped to a single project. A project key always operates on its own project.

Organization-scoped keys

Organization API keys start with oc_org_ and can operate across projects. For project-scoped endpoints, include the X-Project-Id header to specify which project (without it, project endpoints return 401):

curl https://api.onecli.sh/v1/agents \
  -H "Authorization: Bearer oc_org_your_key_here" \
  -H "X-Project-Id: proj_abc123"

Organization endpoints (/org/...) need no project header, and require the admin or owner role, with one exception: GET /org/partner/inherited-secrets is readable by any organization member (project pages surface those inherited secrets).

Partner keys

Partner API keys start with oc_partner_ and let resellers and agencies provision and manage organizations for their customers. See the Partner API for the full workflow.

Errors

The API returns standard HTTP status codes. Validation errors return a flat error string; authentication and service errors use an envelope with message and type:

Validation error

{
  "error": "Label is required"
}

{
  "error": {
    "message": "Invalid API key or token.",
    "type": "authentication_error"
  }
}

Status	Meaning
400	Validation error or bad request
401	Missing or invalid authentication
403	Insufficient permissions (role-gated endpoint)
404	Resource not found
409	Conflict (e.g., duplicate identifier)

See Errors for the full reference.

Rate limits

The gateway enforces rate limits on proxied requests via policy rules.