Agents

All agent endpoints require authentication via Bearer token.

List agents

Retrieve all agents for the authenticated user.

Headers

string

required

Bearer token for authentication. Format: Bearer <jwt>

Response

Returns an array of agent objects.

object[]

Show properties

number

Unique agent identifier.

number

Owner user ID.

string

Agent name.

string

First 12 characters of the API key for identification.

boolean

Whether the agent is active (can make requests).

string

ISO 8601 timestamp of last API request. Null if never used.

object[]

Array of services this agent can access.

string

ISO 8601 timestamp of agent creation.

string

ISO 8601 timestamp of last update.

Status codes

200 - Agents retrieved successfully
401 - Unauthorized (missing or invalid token)
500 - Internal server error

curl --request GET \
  --url https://api.gaiterguard.com/agents \
  --header 'Authorization: Bearer <jwt>'

const response = await fetch('https://api.gaiterguard.com/agents', {
  headers: {
    'Authorization': 'Bearer <jwt>'
  }
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.gaiterguard.com/agents',
    headers={'Authorization': 'Bearer <jwt>'}
)
data = response.json()

[
  {
    "id": 1,
    "userId": 1,
    "name": "Production Agent",
    "keyPrefix": "gg_prod_abc1",
    "isActive": true,
    "lastUsedAt": "2026-03-03T22:49:00.000Z",
    "services": [
      {
        "id": 1,
        "name": "GitHub API"
      }
    ],
    "createdAt": "2026-03-01T10:00:00.000Z",
    "updatedAt": "2026-03-03T22:49:00.000Z"
  }
]

Create agent

Create a new agent with an API key and service permissions.

The full API key is only shown once during creation. Store it securely.

Headers

string

required

Bearer token for authentication. Format: Bearer <jwt>

Request body

string

required

Agent name (3-100 characters).

number[]

required

Array of service IDs this agent can access. Must contain at least one valid service ID owned by the user.

Response

object

Show properties

number

Unique agent identifier.

number

Owner user ID.

string

Agent name.

string

First 12 characters of the API key.

boolean

Whether the agent is active.

object[]

Array of services this agent can access.

string

ISO 8601 timestamp of agent creation.

string

ISO 8601 timestamp of last update.

string

Full API key. Only returned during creation. Store securely.

Status codes

201 - Agent created successfully
400 - Validation error (invalid request body)
401 - Unauthorized (missing or invalid token)
404 - One or more service IDs not found
500 - Internal server error

curl --request POST \
  --url https://api.gaiterguard.com/agents \
  --header 'Authorization: Bearer <jwt>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Production Agent",
    "serviceIds": [1, 2]
  }'

const response = await fetch('https://api.gaiterguard.com/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <jwt>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Production Agent',
    serviceIds: [1, 2]
  })
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.gaiterguard.com/agents',
    headers={'Authorization': 'Bearer <jwt>'},
    json={
        'name': 'Production Agent',
        'serviceIds': [1, 2]
    }
)
data = response.json()

{
  "agent": {
    "id": 1,
    "userId": 1,
    "name": "Production Agent",
    "keyPrefix": "gg_prod_abc1",
    "isActive": true,
    "services": [
      {
        "id": 1,
        "name": "GitHub API"
      },
      {
        "id": 2,
        "name": "Stripe API"
      }
    ],
    "createdAt": "2026-03-03T22:49:00.000Z",
    "updatedAt": "2026-03-03T22:49:00.000Z"
  },
  "apiKey": "gg_prod_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
}

{
  "error": "At least one service ID is required"
}

Get agent

Retrieve a single agent by ID. Ownership is verified.

Headers

string

required

Bearer token for authentication. Format: Bearer <jwt>

Path parameters

number

required

Agent ID.

Response

number

Unique agent identifier.

number

Owner user ID.

string

Agent name.

string

First 12 characters of the API key.

boolean

Whether the agent is active.

string

ISO 8601 timestamp of last API request.

object[]

Array of services this agent can access.

string

ISO 8601 timestamp of agent creation.

string

ISO 8601 timestamp of last update.

Status codes

200 - Agent retrieved successfully
400 - Invalid agent ID
401 - Unauthorized (missing or invalid token)
404 - Agent not found
500 - Internal server error

curl --request GET \
  --url https://api.gaiterguard.com/agents/1 \
  --header 'Authorization: Bearer <jwt>'

const response = await fetch('https://api.gaiterguard.com/agents/1', {
  headers: {
    'Authorization': 'Bearer <jwt>'
  }
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.gaiterguard.com/agents/1',
    headers={'Authorization': 'Bearer <jwt>'}
)
data = response.json()

{
  "id": 1,
  "userId": 1,
  "name": "Production Agent",
  "keyPrefix": "gg_prod_abc1",
  "isActive": true,
  "lastUsedAt": "2026-03-03T22:49:00.000Z",
  "services": [
    {
      "id": 1,
      "name": "GitHub API"
    }
  ],
  "createdAt": "2026-03-01T10:00:00.000Z",
  "updatedAt": "2026-03-03T22:49:00.000Z"
}

{
  "error": "Resource not found"
}

Update agent

Update agent details (name or active status).

Headers

string

required

Bearer token for authentication. Format: Bearer <jwt>

Path parameters

number

required

Agent ID.

Request body

string

Agent name (3-100 characters). Optional.

boolean

Whether the agent is active. Set to false to revoke access. Optional.

At least one field must be provided for update.

Response

Returns the updated agent object.

Status codes

200 - Agent updated successfully
400 - Validation error (invalid agent ID or request body)
401 - Unauthorized (missing or invalid token)
404 - Agent not found
500 - Internal server error

curl --request PUT \
  --url https://api.gaiterguard.com/agents/1 \
  --header 'Authorization: Bearer <jwt>' \
  --header 'Content-Type: application/json' \
  --data '{
    "isActive": false
  }'

const response = await fetch('https://api.gaiterguard.com/agents/1', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer <jwt>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    isActive: false
  })
});
const data = await response.json();

import requests

response = requests.put(
    'https://api.gaiterguard.com/agents/1',
    headers={'Authorization': 'Bearer <jwt>'},
    json={'isActive': False}
)
data = response.json()

{
  "id": 1,
  "userId": 1,
  "name": "Production Agent",
  "keyPrefix": "gg_prod_abc1",
  "isActive": false,
  "lastUsedAt": "2026-03-03T22:49:00.000Z",
  "services": [
    {
      "id": 1,
      "name": "GitHub API"
    }
  ],
  "createdAt": "2026-03-01T10:00:00.000Z",
  "updatedAt": "2026-03-03T23:15:00.000Z"
}

Delete agent

Delete an agent. This cascades to delete all agent-service associations.

This action is irreversible. The agent’s API key will be permanently revoked.

Headers

string

required

Bearer token for authentication. Format: Bearer <jwt>

Path parameters

number

required

Agent ID.

Response

string

Success message confirming deletion.

Status codes

200 - Agent deleted successfully
400 - Invalid agent ID
401 - Unauthorized (missing or invalid token)
404 - Agent not found
500 - Internal server error

curl --request DELETE \
  --url https://api.gaiterguard.com/agents/1 \
  --header 'Authorization: Bearer <jwt>'

const response = await fetch('https://api.gaiterguard.com/agents/1', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer <jwt>'
  }
});
const data = await response.json();

import requests

response = requests.delete(
    'https://api.gaiterguard.com/agents/1',
    headers={'Authorization': 'Bearer <jwt>'}
)
data = response.json()

{
  "message": "Agent deleted"
}

Update agent services

Update the services an agent can access. This replaces all existing service associations.

This replaces ALL service associations. Any services not included will be removed from the agent’s access.

Headers

string

required

Bearer token for authentication. Format: Bearer <jwt>

Path parameters

number

required

Agent ID.

Request body

number[]

required

Array of service IDs this agent can access. Must contain at least one valid service ID owned by the user.

Response

string

Success message confirming service update.

object[]

Array of services this agent can now access.

Status codes

200 - Agent services updated successfully
400 - Validation error (invalid agent ID or request body)
401 - Unauthorized (missing or invalid token)
404 - Agent or one or more services not found
500 - Internal server error

curl --request PUT \
  --url https://api.gaiterguard.com/agents/1/services \
  --header 'Authorization: Bearer <jwt>' \
  --header 'Content-Type: application/json' \
  --data '{
    "serviceIds": [1, 3]
  }'

const response = await fetch('https://api.gaiterguard.com/agents/1/services', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer <jwt>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    serviceIds: [1, 3]
  })
});
const data = await response.json();

import requests

response = requests.put(
    'https://api.gaiterguard.com/agents/1/services',
    headers={'Authorization': 'Bearer <jwt>'},
    json={'serviceIds': [1, 3]}
)
data = response.json()

{
  "message": "Agent services updated",
  "services": [
    {
      "id": 1,
      "name": "GitHub API"
    },
    {
      "id": 3,
      "name": "Slack API"
    }
  ]
}

{
  "error": "At least one service ID is required"
}

Authentication

Agent Endpoints

Dashboard Endpoints

Reference

List agents

Headers

Response

Status codes

Create agent

Headers

Request body

Response

Status codes

Get agent

Headers

Path parameters

Response

Status codes

Update agent

Headers

Path parameters

Request body

Response

Status codes

Delete agent

Headers

Path parameters

Response

Status codes

Update agent services

Headers

Path parameters

Request body

Response

Status codes

​List agents

​Headers

​Response

​Status codes

​Create agent

​Headers

​Request body

​Response

​Status codes

​Get agent

​Headers

​Path parameters

​Response

​Status codes

​Update agent

​Headers

​Path parameters

​Request body

​Response

​Status codes

​Delete agent

​Headers

​Path parameters

​Response

​Status codes

​Update agent services

​Headers

​Path parameters

​Request body

​Response

​Status codes

List agents

Headers

Response

Status codes

Create agent

Headers

Request body

Response

Status codes

Get agent

Headers

Path parameters

Response

Status codes

Update agent

Headers

Path parameters

Request body

Response

Status codes

Delete agent

Headers

Path parameters

Response

Status codes

Update agent services

Headers

Path parameters

Request body

Response

Status codes