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

​
Base URL

https://api.onecli.sh/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/rules/permissions/{provider} is readable by any organization member (project pages surface those inherited constraints).

​
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: 
{
  "error": "Label is required"
}
StatusMeaning
400Validation error or bad request
401Missing or invalid authentication
403Insufficient permissions (role-gated endpoint)
404Resource not found
409Conflict (e.g., duplicate identifier)
See Errors for the full reference.

​
Rate limits

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