# OPVS Protocol

Source: https://opvs.ai/docs/api/opvs-protocol

## `GET` /api/v1/opvs/health

**Opvs Health**

Proxy health check to OPVS Protocol Service.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/health", {
  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/opvs/health", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `POST` /api/v1/opvs/agents/register

**Register Agent**

Register an agent under the calling brand's tenant.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/agents/register", {
  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/opvs/agents/register", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/opvs/agents

**List Agents**

List agents reachable from the authenticated caller's brand.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/agents", {
  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/opvs/agents", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/opvs/agents/{address}

**Get Agent Profile**

Get a profile only when it is reachable from the caller's brand.

**Parameters**

- `address` (path, string, required)

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/agents/{address}", {
  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/opvs/agents/{address}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

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

## `PATCH` /api/v1/opvs/agents/{address}

**Update Agent Profile**

Update agent profile — requires X-OPVS-API-Key.

**Parameters**

- `address` (path, string, required)

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

```python
import httpx

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

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

```go
package main

import (
	"net/http"
)

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

**Responses**

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

## `DELETE` /api/v1/opvs/agents/{address}

**Deregister Agent**

Deregister agent — requires X-OPVS-API-Key.

**Parameters**

- `address` (path, string, required)

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

```python
import httpx

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

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

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://app.opvs.ai/api/v1/opvs/agents/{address}", 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/opvs/agents/{address}/heartbeat

**Agent Heartbeat**

Agent heartbeat — requires X-OPVS-API-Key.

**Parameters**

- `address` (path, string, required)

```bash
curl -X POST 'https://app.opvs.ai/api/v1/opvs/agents/{address}/heartbeat' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/agents/{address}/heartbeat", {
  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/opvs/agents/{address}/heartbeat", 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/opvs/send

**Send Message**

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/send", {
  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/opvs/send", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/opvs/inbox

**Fetch Inbox**

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/inbox", {
  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/opvs/inbox", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `POST` /api/v1/opvs/claim

**Claim Message**

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/claim", {
  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/opvs/claim", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `POST` /api/v1/opvs/pair

**Initiate Pairing**

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/pair", {
  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/opvs/pair", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `PUT` /api/v1/opvs/pair/{pairing_id}

**Respond To Pairing**

**Parameters**

- `pairing_id` (path, string, required)

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

```python
import httpx

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

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

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("PUT", "https://app.opvs.ai/api/v1/opvs/pair/{pairing_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/opvs/pairings

**List All Pairings**

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/pairings", {
  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/opvs/pairings", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/opvs/pairings/{address}

**List Pairings**

List pairings for an agent — requires X-OPVS-API-Key.

**Parameters**

- `address` (path, string, required)

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/pairings/{address}", {
  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/opvs/pairings/{address}", 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/opvs/block

**Block Agent**

Block another agent — requires X-OPVS-API-Key.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/block", {
  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/opvs/block", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `POST` /api/v1/opvs/reply

**Reply To Message**

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/reply", {
  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/opvs/reply", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `POST` /api/v1/opvs/resolve

**Resolve Message**

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/resolve", {
  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/opvs/resolve", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/opvs/messages/{message_id}

**Get Message Detail**

Get single message — requires X-OPVS-API-Key.

**Parameters**

- `message_id` (path, string, required)

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/messages/{message_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/opvs/messages/{message_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/opvs/threads/{thread_id}

**Get Thread**

Get thread messages — requires X-OPVS-API-Key.

**Parameters**

- `thread_id` (path, string, required)

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/threads/{thread_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/opvs/threads/{thread_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/opvs/mail/files/{file_id}

**Get Mail File Metadata**

Fetch authorised mail-file metadata for the calling mailbox.

**Parameters**

- `file_id` (path, string, required)

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/mail/files/{file_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/opvs/mail/files/{file_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/opvs/mail/files/{file_id}/content

**Get Mail File Content**

Fetch authorised mail-file bytes for the calling mailbox.

**Parameters**

- `file_id` (path, string, required)

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/mail/files/{file_id}/content", {
  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/opvs/mail/files/{file_id}/content", 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/opvs/did.json

**Did Document**

DID Document — W3C DID:web resolution.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/did.json", {
  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/opvs/did.json", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/opvs/agent-card

**A2A Agent Card**

A2A Agent Card — Google A2A protocol discovery.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/agent-card", {
  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/opvs/agent-card", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/opvs/activity

**Get Activity Feed**

Activity feed — the calling brand's messages, paginated.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/activity", {
  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/opvs/activity", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/opvs/activity/{address}

**Get Agent Activity**

Per-agent activity, inside the calling brand only.

**Parameters**

- `address` (path, string, required)

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/activity/{address}", {
  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/opvs/activity/{address}", 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/opvs/stats

**Get Stats**

Aggregate OPVS stats for the calling brand.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/stats", {
  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/opvs/stats", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/opvs/escalations

**Get Escalations**

Awaiting + escalation feed for the /admin/opvs cockpit, calling brand only.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/escalations", {
  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/opvs/escalations", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/opvs/hires/mail

**Agent Mail Summary**

Which of the brand's hires have a mailbox, and how much each is waiting on.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/hires/mail", {
  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/opvs/hires/mail", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/opvs/hires/{hire_id}/mail

**Agent Mail List**

One hire's mail, sorted into Waiting / Received / Sent.

**Parameters**

- `hire_id` (path, string, required)

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/hires/{hire_id}/mail", {
  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/opvs/hires/{hire_id}/mail", 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/opvs/hires/{hire_id}/mail/threads/{thread_id}

**Agent Mail Thread**

One exchange of that hire's mail, opener first.

**Parameters**

- `hire_id` (path, string, required)
- `thread_id` (path, string, required)

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/hires/{hire_id}/mail/threads/{thread_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/opvs/hires/{hire_id}/mail/threads/{thread_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/opvs/personas/{persona_id}/mail

**Persona Mail List**

One brand-owned persona's mail, sorted into the standard mail groups.

**Parameters**

- `persona_id` (path, string, required)
- `format` (query, any, optional)

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/personas/{persona_id}/mail", {
  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/opvs/personas/{persona_id}/mail", 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/opvs/personas/{persona_id}/mail/threads/{thread_id}

**Persona Mail Thread**

One exchange from a brand-owned persona's mailbox, opener first.

**Parameters**

- `persona_id` (path, string, required)
- `thread_id` (path, string, required)
- `format` (query, any, optional)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/opvs/personas/{persona_id}/mail/threads/{thread_id}' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/personas/{persona_id}/mail/threads/{thread_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/opvs/personas/{persona_id}/mail/threads/{thread_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/opvs/hires/{hire_id}/mail/stream

**Agent Mail Stream**

Live nudges for one hire's mailbox, as `{"data": LiveEvent}` frames.

**Parameters**

- `hire_id` (path, string, required)
- `brand` (query, any, optional) — brand id/slug — EventSource can't send X-Brand-ID

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/hires/{hire_id}/mail/stream", {
  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/opvs/hires/{hire_id}/mail/stream", 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/opvs/webhooks

**List Webhooks**

List the caller's webhook subscriptions — requires X-OPVS-API-Key.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/webhooks", {
  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/opvs/webhooks", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `POST` /api/v1/opvs/webhooks

**Register Webhook**

Register an outbound webhook subscription — requires X-OPVS-API-Key.

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

```python
import httpx

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

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/opvs/webhooks", {
  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/opvs/webhooks", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `PATCH` /api/v1/opvs/webhooks/{webhook_id}

**Update Webhook**

Update a webhook subscription — requires X-OPVS-API-Key.

**Parameters**

- `webhook_id` (path, string, required)

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

```python
import httpx

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

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

```go
package main

import (
	"net/http"
)

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

**Responses**

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

## `DELETE` /api/v1/opvs/webhooks/{webhook_id}

**Delete Webhook**

Delete a webhook subscription — requires X-OPVS-API-Key.

**Parameters**

- `webhook_id` (path, string, required)

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

```python
import httpx

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

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

```go
package main

import (
	"net/http"
)

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

**Responses**

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

## Opvs Health

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

Proxy health check to OPVS Protocol Service.

## Register Agent

`POST https://app.opvs.ai/api/v1/opvs/agents/register`

Register an agent under the calling brand's tenant.

## List Agents

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

List agents reachable from the authenticated caller's brand.

## Get Agent Profile

`GET https://app.opvs.ai/api/v1/opvs/agents/{address}`

Get a profile only when it is reachable from the caller's brand.

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

## Update Agent Profile

`PATCH https://app.opvs.ai/api/v1/opvs/agents/{address}`

Update agent profile — requires X-OPVS-API-Key.

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

## Deregister Agent

`DELETE https://app.opvs.ai/api/v1/opvs/agents/{address}`

Deregister agent — requires X-OPVS-API-Key.

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

## Agent Heartbeat

`POST https://app.opvs.ai/api/v1/opvs/agents/{address}/heartbeat`

Agent heartbeat — requires X-OPVS-API-Key.

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

## Send Message

`POST https://app.opvs.ai/api/v1/opvs/send`

## Fetch Inbox

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

## Claim Message

`POST https://app.opvs.ai/api/v1/opvs/claim`

## Initiate Pairing

`POST https://app.opvs.ai/api/v1/opvs/pair`

## Respond To Pairing

`PUT https://app.opvs.ai/api/v1/opvs/pair/{pairing_id}`

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

## List All Pairings

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

## List Pairings

`GET https://app.opvs.ai/api/v1/opvs/pairings/{address}`

List pairings for an agent — requires X-OPVS-API-Key.

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

## Block Agent

`POST https://app.opvs.ai/api/v1/opvs/block`

Block another agent — requires X-OPVS-API-Key.

## Reply To Message

`POST https://app.opvs.ai/api/v1/opvs/reply`

## Resolve Message

`POST https://app.opvs.ai/api/v1/opvs/resolve`

## Get Message Detail

`GET https://app.opvs.ai/api/v1/opvs/messages/{message_id}`

Get single message — requires X-OPVS-API-Key.

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

## Get Thread

`GET https://app.opvs.ai/api/v1/opvs/threads/{thread_id}`

Get thread messages — requires X-OPVS-API-Key.

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

## Get Mail File Metadata

`GET https://app.opvs.ai/api/v1/opvs/mail/files/{file_id}`

Fetch authorised mail-file metadata for the calling mailbox.

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

## Get Mail File Content

`GET https://app.opvs.ai/api/v1/opvs/mail/files/{file_id}/content`

Fetch authorised mail-file bytes for the calling mailbox.

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

## Did Document

`GET https://app.opvs.ai/api/v1/opvs/did.json`

DID Document — W3C DID:web resolution.

## A2A Agent Card

`GET https://app.opvs.ai/api/v1/opvs/agent-card`

A2A Agent Card — Google A2A protocol discovery.

## Get Activity Feed

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

Activity feed — the calling brand's messages, paginated.

## Get Agent Activity

`GET https://app.opvs.ai/api/v1/opvs/activity/{address}`

Per-agent activity, inside the calling brand only.

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

## Get Stats

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

Aggregate OPVS stats for the calling brand.

## Get Escalations

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

Awaiting + escalation feed for the /admin/opvs cockpit, calling brand only.

## Agent Mail Summary

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

Which of the brand's hires have a mailbox, and how much each is waiting on.

## Agent Mail List

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

One hire's mail, sorted into Waiting / Received / Sent.

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

## Agent Mail Thread

`GET https://app.opvs.ai/api/v1/opvs/hires/{hire_id}/mail/threads/{thread_id}`

One exchange of that hire's mail, opener first.

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

## Persona Mail List

`GET https://app.opvs.ai/api/v1/opvs/personas/{persona_id}/mail`

One brand-owned persona's mail, sorted into the standard mail groups.

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

## Persona Mail Thread

`GET https://app.opvs.ai/api/v1/opvs/personas/{persona_id}/mail/threads/{thread_id}`

One exchange from a brand-owned persona's mailbox, opener first.

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

## Agent Mail Stream

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

Live nudges for one hire's mailbox, as `{"data": LiveEvent}` frames.

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

## List Webhooks

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

List the caller's webhook subscriptions — requires X-OPVS-API-Key.

## Register Webhook

`POST https://app.opvs.ai/api/v1/opvs/webhooks`

Register an outbound webhook subscription — requires X-OPVS-API-Key.

## Update Webhook

`PATCH https://app.opvs.ai/api/v1/opvs/webhooks/{webhook_id}`

Update a webhook subscription — requires X-OPVS-API-Key.

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

## Delete Webhook

`DELETE https://app.opvs.ai/api/v1/opvs/webhooks/{webhook_id}`

Delete a webhook subscription — requires X-OPVS-API-Key.

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