# Employees

Source: https://opvs.ai/docs/api/employees

## `GET` /api/v1/employees/published

**List Published Employees**

Public catalog: published AI Employees only.

**Parameters**

- `category` (query, any, optional) — Category slug
- `category_id` (query, any, optional)
- `featured` (query, any, optional)
- `min_price` (query, any, optional)
- `max_price` (query, any, optional)
- `search` (query, any, optional)
- `limit` (query, integer, optional)
- `offset` (query, integer, optional)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/employees/published' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/employees/published",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/published", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/employees/published", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/employees

**List Employees**

Admin view: all AI Employee products, filterable.

**Parameters**

- `category` (query, any, optional) — Category slug
- `category_id` (query, any, optional)
- `status` (query, any, optional)
- `featured` (query, any, optional)
- `min_price` (query, any, optional)
- `max_price` (query, any, optional)
- `search` (query, any, optional)
- `limit` (query, integer, optional)
- `offset` (query, integer, optional)
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/employees' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/employees",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/employees", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/employees/hires

**List My Hires**

"Your team": the brand's hired AI employees, one card per hire.

**Parameters**

- `limit` (query, integer, optional)
- `offset` (query, integer, optional)
- `include_inactive` (query, boolean, optional) — Include canceled/failed hires. Default lists only alive hires (rides the agent_hires brand_alive partial index).
- `agent_type` (query, any, optional) — Narrow to one catalog agent_type: 'builder' (ship-PRs workstation hires), 'dev_agent' (desk roles), or 'conversational'. Omit to list every hire type. The dashboard builder section passes 'builder' so conversational hires are never mislabeled as builders (F.TP2).

```bash
curl -X GET 'https://app.opvs.ai/api/v1/employees/hires' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/employees/hires",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/hires", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/employees/hires", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/employees/hires/{hire_id}

**Get My Hire**

One hire card for the onboarding poll. 404 if the brand holds no such hire.

**Parameters**

- `hire_id` (path, string, required)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/employees/hires/{hire_id}' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/employees/hires/{hire_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/hires/{hire_id}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/employees/hires/{hire_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/employees/hires/{hire_id}/profile

**Get My Hire Profile**

The catalog profile a hire was made from, whatever its state is now.

**Parameters**

- `hire_id` (path, string, required)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/employees/hires/{hire_id}/profile' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/employees/hires/{hire_id}/profile",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/hires/{hire_id}/profile", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/employees/hires/{hire_id}/profile", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/employees/hires/{hire_id}/skills

**Get My Hire Skills**

Return installed-package records equipped on a brand-owned hire.

**Parameters**

- `hire_id` (path, string, required)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/employees/hires/{hire_id}/skills' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/employees/hires/{hire_id}/skills",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/hires/{hire_id}/skills", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/employees/hires/{hire_id}/skills", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/employees/by-slug/{slug}

**Get Employee For Admin**

Admin editor read for one employee profile in any publication state.

**Parameters**

- `slug` (path, string, required)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/employees/by-slug/{slug}' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/employees/by-slug/{slug}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/by-slug/{slug}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/employees/by-slug/{slug}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/employees/{profile_id}/hires

**List Profile Hires**

Cross-brand hires drilldown for the admin Hires tab (5.4).

**Parameters**

- `profile_id` (path, string, required)
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/employees/{profile_id}/hires' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/employees/{profile_id}/hires",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/{profile_id}/hires", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/employees/{profile_id}/hires", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/employees/{slug}

**Get Employee**

A single AI Employee product by slug.

**Parameters**

- `slug` (path, string, required)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/employees/{slug}' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/employees/{slug}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/{slug}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/employees/{slug}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

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

**Hire Employee**

Hire an AI Employee — direct provisioning, dispatcher-gated (Wave 8.A).

**Parameters**

- `profile_id` (path, string, required)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/employees/{profile_id}/hire' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/employees/{profile_id}/hire",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/{profile_id}/hire", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/employees/{profile_id}/hire", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/employees/hires/{hire_id}/cancel

**Cancel Hire**

Cancel at period end — the agent keeps running until ``current_period_end``.

**Parameters**

- `hire_id` (path, string, required)

```bash
curl -X POST 'https://app.opvs.ai/api/v1/employees/hires/{hire_id}/cancel' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/employees/hires/{hire_id}/cancel",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/hires/{hire_id}/cancel", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/employees/hires/{hire_id}/cancel", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/employees/hires/{hire_id}/cancel-immediate

**Cancel Hire Immediate**

Cancel now — ref-counted marketplace disable + record delete + ``canceled``.

**Parameters**

- `hire_id` (path, string, required)

```bash
curl -X POST 'https://app.opvs.ai/api/v1/employees/hires/{hire_id}/cancel-immediate' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/employees/hires/{hire_id}/cancel-immediate",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/hires/{hire_id}/cancel-immediate", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/employees/hires/{hire_id}/cancel-immediate", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/employees/hires/{hire_id}/equip

**Equip Hire**

Equip a marketplace package (a profession, or any package) onto a live hire.

**Parameters**

- `hire_id` (path, string, required)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/employees/hires/{hire_id}/equip' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "package_ref": "string",
  "version": "string"
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/employees/hires/{hire_id}/equip",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"package_ref": "string", "version": "string"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/employees/hires/{hire_id}/equip", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"package_ref": "string", "version": "string"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"package_ref": "string", "version": "string"}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/employees/hires/{hire_id}/equip", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## List Published Employees

`GET https://app.opvs.ai/api/v1/employees/published`

Public catalog: published AI Employees only.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## List Employees

`GET https://app.opvs.ai/api/v1/employees`

Admin view: all AI Employee products, filterable.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## List My Hires

`GET https://app.opvs.ai/api/v1/employees/hires`

"Your team": the brand's hired AI employees, one card per hire.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Get My Hire

`GET https://app.opvs.ai/api/v1/employees/hires/{hire_id}`

One hire card for the onboarding poll. 404 if the brand holds no such hire.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Get My Hire Profile

`GET https://app.opvs.ai/api/v1/employees/hires/{hire_id}/profile`

The catalog profile a hire was made from, whatever its state is now.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Get My Hire Skills

`GET https://app.opvs.ai/api/v1/employees/hires/{hire_id}/skills`

Return installed-package records equipped on a brand-owned hire.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Get Employee For Admin

`GET https://app.opvs.ai/api/v1/employees/by-slug/{slug}`

Admin editor read for one employee profile in any publication state.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## List Profile Hires

`GET https://app.opvs.ai/api/v1/employees/{profile_id}/hires`

Cross-brand hires drilldown for the admin Hires tab (5.4).

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Get Employee

`GET https://app.opvs.ai/api/v1/employees/{slug}`

A single AI Employee product by slug.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Hire Employee

`POST https://app.opvs.ai/api/v1/employees/{profile_id}/hire`

Hire an AI Employee — direct provisioning, dispatcher-gated (Wave 8.A).

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Cancel Hire

`POST https://app.opvs.ai/api/v1/employees/hires/{hire_id}/cancel`

Cancel at period end — the agent keeps running until ``current_period_end``.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Cancel Hire Immediate

`POST https://app.opvs.ai/api/v1/employees/hires/{hire_id}/cancel-immediate`

Cancel now — ref-counted marketplace disable + record delete + ``canceled``.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Equip Hire

`POST https://app.opvs.ai/api/v1/employees/hires/{hire_id}/equip`

Equip a marketplace package (a profession, or any package) onto a live hire.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |