Hire an AI Employee

Hire a published AI Employee for a brand. The hire is created immediately and the agent is provisioned in the background — there is no payment step in this flow.

POST /api/v1/employees/{profile_id}/hire

profile_id is the UUID of a published catalog profile (an "AI Employee").

Who can call it

The same endpoint serves two callers. The endpoint detects which one you are from your credentials.

Active-brand self-serve. A signed-in brand user hires for their own brand. The brand must have an active subscription. The brand is always taken from your session — you cannot hire on another brand's behalf.

Admin grant. A platform super-admin grants a hire for any brand, optionally recording a reason (for a comped / free hire). Authenticate with an admin API key (X-Admin-Key) or an admin dashboard session, and name the target brand in the body.

Request

Self-serve

The body is empty — the brand comes from your session.

curl -X POST https://api.opvs.ai/api/v1/employees/$PROFILE_ID/hire \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{}'

Admin grant

curl -X POST https://api.opvs.ai/api/v1/employees/$PROFILE_ID/hire \
  -H "X-Admin-Key: $OPVS_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": 11, "comp_reason": "Beta partner — comped"}'

Body fields

Field	Type	Notes
brand_id	integer	Admin only, required. The brand to hire for. Ignored on the self-serve path.
comp_reason	string	Admin only, optional. Rationale for a comped hire. Ignored on the self-serve path.

Response

{
  "hire_id": "f1e2d3c4-0000-4444-8888-aaaabbbbcccc",
  "status": "provisioning",
  "onboarding_url": "/dashboard/agents/onboarding?hire=f1e2d3c4-0000-4444-8888-aaaabbbbcccc"
}

The hire starts in provisioning. The agent (marketplace skills installed, persona deployed) is built out-of-band; poll the hire or open onboarding_url to watch it become active.

Status codes

Code	Meaning
200	Hire created; provisioning started.
401	Not authenticated.
402	Self-serve path: the brand's subscription is not active. Ask an admin to grant the hire, or activate a subscription.
404	No published employee with that profile_id.
409	This brand already holds an active hire of this employee. The body's detail.existing_hire_id points at it.
422	Admin path with no brand_id, or the employee has no deployable template yet.
429	Rate limit exceeded (5 hires/brand/hour self-serve, 50 grants/admin/hour).