Agent Servers

Agent server records tell Sharely.ai where your custom agent is hosted. Register your server's URL, then bind threads to it via agentServerId — the platform dispatches those threads' chat turns to your server.

Build the server itself with the open-source Sharely Server SDK.

Register Agent Server

POST /v1/workspaces/{workspaceId}/agent/servers

Request Body

FieldTypeRequiredDescription
namestringYesDisplay name (e.g. "legal-research-agent")
urlstringYesPublic HTTPS base URL of your agent server
statusstringNoDefaults to "ACTIVE"
metadataobjectNoArbitrary JSON (e.g. owner, environment, version)

Example Request

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/servers' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "legal-research-agent",
    "url": "https://agent.example.com",
    "metadata": { "environment": "production" }
  }'

Response (201 Created)

{
  "id": "9f6c1e2a-7b3d-4e5f-8a90-123456789abc",
  "name": "legal-research-agent",
  "url": "https://agent.example.com",
  "status": "ACTIVE",
  "metadata": { "environment": "production" },
  "workspaceId": "workspace-uuid",
  "createdAt": "2026-06-11T10:00:00.000Z",
  "updatedAt": "2026-06-11T10:00:00.000Z",
  "deletedAt": null
}

List Agent Servers

GET /v1/workspaces/{workspaceId}/agent/servers

Example Request

curl 'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/servers' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (200 OK)

{
  "items": [
    {
      "id": "9f6c1e2a-7b3d-4e5f-8a90-123456789abc",
      "name": "legal-research-agent",
      "url": "https://agent.example.com",
      "status": "ACTIVE",
      "metadata": { "environment": "production" },
      "createdAt": "2026-06-11T10:00:00.000Z",
      "updatedAt": "2026-06-11T10:00:00.000Z"
    }
  ]
}

Get Agent Server

GET /v1/workspaces/{workspaceId}/agent/servers/{id}

Response (200 OK)

Same shape as registration. Returns 404 if the server does not exist or has been deleted.

Update Agent Server

PATCH /v1/workspaces/{workspaceId}/agent/servers/{id}

Partial update — only the fields you supply are changed.

Request Body

FieldTypeRequiredDescription
namestringNoNew display name
urlstringNoNew base URL
statusstringNoe.g. "ACTIVE"
metadataobjectNoReplaces stored metadata

Example Request

curl -X PATCH \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/servers/{id}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "url": "https://agent-v2.example.com" }'

Response (200 OK)

The updated server record.

Delete Agent Server

DELETE /v1/workspaces/{workspaceId}/agent/servers/{id}

Soft delete — the record's status becomes DELETED and it no longer appears in list/get responses.

Example Request

curl -X DELETE \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/servers/{id}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

204 No Content

Related