Agents API reference

An Agent is the core identity unit in Synentra. Every autonomous AI agent, service, or system that proxies requests through Synentra must be registered as an agent. Each agent has a unique identity, a trust score, an assigned policy, and a lifecycle status.

Base URL

Throughout this guide the base URL is assumed to be your running server, e.g. http://localhost:7080. Replace <BASE_URL> in the examples with your actual server address.

---

API Endpoints

Get agents list

Returns a paginated list of all registered agents.

GET <BASE_URL>/agents?page=1&pageSize=25

URL Parameters

Parameter	Type	Default	Description
page	int	1	Page number
pageSize	int	25	Items per page

Examples

Example of invoking a method on an action:

cURL

curl "http://localhost:7080/agents?page=1&pageSize=25"

JavaScript

fetch(`http://localhost:7080/agents?page=1&pageSize=25`)
.then(res => res.json())
.then(console.log);

Python

import requests

response = requests.get(
    f'http://localhost:7080/agents',
    params={'page': 1, 'pageSize': 25}
)
print(response.json())

Response 200 OK

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "billing-agent",
      "ownerId": "team-finance",
      "status": "Active",
      "policyName": "billing-policy",
      "trustScore": 0.75
    }
  ],
  "page": 1,
  "pageSize": 25,
  "totalCount": 1
}

---

Register an agent

POST <BASE_URL>/agents

Request body

A JSON object with the following fields:

{
  "name": "billing-agent",
  "ownerId": "team-finance",
  "clientSecret": "my-strong-secret"
}

Field	Required	Description
name	✅	Human-readable name
ownerId	✅	Owner identifier
clientSecret	✅	Secret used to obtain JWT tokens

warning

The clientSecret is only returned once. Store it securely — Synentra only stores the bcrypt hash.

Examples

cURL

curl -X POST "http://localhost:7080/agents" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "billing-agent",
    "ownerId": "team-finance",
    "clientSecret": "my-strong-secret"
  }'

JavaScript

fetch(`http://localhost:7080/agents`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'billing-agent',
    ownerId: 'team-finance',
    clientSecret: 'my-strong-secret'
  })
})
.then(res => res.json())
.then(console.log);

Python

import requests

response = requests.post(
    f'http://localhost:7080/agents',
    json={
        'name': 'billing-agent',
        'ownerId': 'team-finance',
        'clientSecret': 'my-strong-secret'
    }
)
print(response.json())

Response 201 Created

---

Assign policy

PUT <BASE_URL>/agents/<agentId>/policy

Request body

A JSON object with the following fields:

{
  "policyName": "billing-policy"
}

Examples

cURL

curl -X PUT "http://localhost:7080/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/policy" \
  -H "Content-Type: application/json" \
  -d '{ "policyName": "billing-policy" }'

JavaScript

fetch(`http://localhost:7080/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/policy`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ policyName: 'billing-policy' })
})
.then(res => {
  if (res.ok) console.log('Policy assigned');
});

Python

import requests

response = requests.put(
    f'http://localhost:7080/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/policy',
    json={'policyName': 'billing-policy'}
)
print(response.status_code)

Response 200 OK

---

Delete an agent

DELETE <BASE_URL>/agents/<agentId>

Examples

cURL

curl -X DELETE "http://localhost:7080/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6"

JavaScript

fetch(`http://localhost:7080/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6`, {
  method: 'DELETE'
})
.then(res => {
  if (res.ok) console.log('Agent deleted');
});

Python

import requests

response = requests.delete(
    f'http://localhost:7080/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6'
)
print(response.status_code)

Response 200 OK

---

Lift quarantine

POST <BASE_URL>/agents/<agentId>/lift-quarantine

Examples

cURL

curl -X POST "${BASE_URL}/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/lift-quarantine"

JavaScript

fetch(`${BASE_URL}/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/lift-quarantine`, {
  method: 'POST'
})
.then(res => {
  if (res.ok) console.log('Quarantine lifted');
});

Python

import requests

response = requests.post(
    f'{BASE_URL}/agents/3fa85f64-5717-4562-b3fc-2c963f66afa6/lift-quarantine'
)
print(response.status_code)

Response 200 OK