API reference

The REST surface is mounted at /v1/modules/scailink/ and authenticates with the standard ScaiGrid bearer token. The desktop WebSocket lives at /v1/scailink/ws and authenticates with a user JWT in the Authorization header. Responses use ScaiGrid's standard envelope: { "data": ... } for success, { "error": ... } for failures.

Auth discovery#

GET /v1/scailink/auth/discover#

Public, unauthenticated. The first endpoint a desktop client calls. Returns OAuth metadata so the client knows where to send the user for sign-in.

1

curl "$SCAIGRID_HOST/v1/scailink/auth/discover"

Response fields: issuer, authorization_endpoint, token_endpoint, device_authorization_endpoint, userinfo_endpoint, jwks_uri, scopes_supported, grant_types_supported, client_id, audience, gateway_ws.

Desktop WebSocket#

WS /v1/scailink/ws#

Authenticated WebSocket carrying JSON-RPC 2.0 frames. The first frame from the client must be scailink/session_init; anything else closes the connection with code 4002.

Client-to-server methods:

Server-to-client methods:

Custom JSON-RPC error codes: -32000 TOOL_ERROR, -32001 CONSENT_DENIED, -32002 CONSENT_TIMEOUT, -32003 SCOPE_BLOCKED, -32004 QUEUE_FULL, -32005 TIMEOUT, -32006 CLIENT_DISCONNECTED.

Sessions#

GET /sessions#

List the caller's own active ScaiLink sessions across all their devices.

GET /sessions/all#

List all active sessions in the caller's tenant. Requires scailink:manage.

GET /users/{user_id}/sessions#

List active sessions for a specific user. Cross-user reads require same-tenant access; super admin bypasses tenant isolation. user_id accepts either a ScaiGrid UUID or a ScaiKey usr_... id.

Capabilities#

GET /capabilities#

Aggregated capability catalog for the caller — tools, resources, and prompts across all of the caller's connected devices.

GET /users/{user_id}/capabilities#

Same shape, for a specific user. Tenant-bounded unless the caller is super admin.

GET /device/{device_id}#

Capability catalog for a single device. Useful when a user has multiple machines connected and you want to invoke against one specifically.

Invocations#

All four below require scailink:invoke.

POST /users/{user_id}/tools/{tool_name}/invoke#

Invoke a tool on the user's connected device.

1
2
3
4

curl -X POST "$SCAIGRID_HOST/v1/modules/scailink/users/$USER_ID/tools/filesystem.read_file/invoke" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"path": "/Users/alice/notes.md"}}'

Returns { "data": { "result": ..., "error": null, "duration_ms": 145, "device_id": "..." } }.

POST /users/{user_id}/resources/{resource_uri:path}/read#

Read a resource (e.g. a file URI) from the user's device. The URI is in the path; encode / characters appropriately.

POST /users/{user_id}/prompts/{prompt_name}/get#

Retrieve a prompt from the user's device.

POST /consent/{consent_id}/resolve#

Resolve a pending consent request out of band — when the user approves or denies through a UI separate from the WebSocket itself.

Audit#

GET /audit#

Tenant-wide audit log. Requires scailink:audit.

Query parameters: limit (1-200, default 50), offset (default 0).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "data": [
    {
      "id": "evt_...",
      "action": "tool_invoke",
      "target_name": "filesystem.read_file",
      "status": "approved",
      "duration_ms": 145,
      "device_id": "...",
      "detail_level": "metadata",
      "created_at": "2026-05-17T12:00:00Z"
    }
  ]
}

GET /users/{user_id}/audit#

Per-user audit log. Same shape, scoped to one user. scailink:audit required.

Cloud MCP registry#

All endpoints below are under /v1/modules/scailink/remote-servers. Every call requires scailink:remote.use as the precondition; mutating calls additionally require manage_own (for personal servers) or manage_tenant (for tenant-shared).

GET /remote-servers#

List servers visible to the caller — their own personal servers plus any tenant-shared servers in the caller's tenant.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
  "data": {
    "items": [
      {
        "id": "...",
        "tenant_id": "...",
        "owner_user_id": "...",
        "is_tenant_shared": false,
        "name": "Acme Notion MCP",
        "slug": "acme-notion-mcp-a1b2c3",
        "endpoint_url": "https://...",
        "transport": "streamable_http",
        "auth_type": "bearer",
        "forward_user_id": false,
        "consent_tier": "auto",
        "status": "active",
        "last_health_check_at": "...",
        "last_health_status": "ok",
        "consecutive_failures": 0,
        "created_at": "..."
      }
    ]
  }
}

GET /remote-servers/{id}#

Detail view. Same fields as list plus capabilities (discovered tools/resources/prompts), credential_fields (the field names you can rotate), and credential_oldest_days.

POST /remote-servers#

Register a new server. Returns 201 Created.

Registration triggers an immediate discovery. The row is committed even if discovery fails (status='error').

DELETE /remote-servers/{id}#

Remove the server. Cascades through mod_scailink_remote_credential and mod_scailink_remote_capability. Personal servers need manage_own; tenant-shared need manage_tenant.

POST /remote-servers/{id}/refresh#

Force re-discovery. Updates capability rows and health. Gated on scailink:remote.use (same perm as listing).

PUT /remote-servers/{id}/credentials/{field}#

Rotate one credential field. Idempotent — overwrites the existing ciphertext and DEK.

Body: { "value": "..." }.

Personal servers need manage_own; tenant-shared need manage_tenant.

Errors#

All endpoints return ScaiGrid's standard error envelope:

1
2
3
4
5
6
7
8

{
  "error": {
    "code": "SCAILINK_REMOTE_SERVER_NOT_FOUND",
    "message": "Remote MCP server not found",
    "details": { "server_id": "..." }
  },
  "meta": { "request_id": "req_..." }
}

ScaiLink-specific codes:

WebSocket close codes you may see from the desktop bridge: