Connections API

Use the Connections API to manage your UsageGuard connections programmatically. Connections allow you to integrate with different AI providers and apply policies to control usage, spending, and monitoring.

Required Headers

All API endpoints require these headers:

Name
Authorization
Type
string
Description
Bearer token for authentication. Format: 'Bearer your-token-here'
Name
traceparent
Type
string
Description
OpenTelemetry trace parent for distributed tracing
Name
tracestate
Type
string
Description
OpenTelemetry trace state information

Connection Model

A connection represents an integration with an AI provider. It defines how requests are handled, logged, and controlled.

Name
name
Type
string
Description
A friendly name to identify the connection. Must be unique within your organization.
Name
logRequestBody
Type
boolean
Description
Whether to log request bodies for auditing and debugging.
Name
logResponseBody
Type
boolean
Description
Whether to log response bodies for auditing and debugging.
Name
enableSpendingLimit
Type
boolean
Description
Enable cost control with spending limits.
Name
spendingLimit
Type
decimal
Description
Maximum amount allowed to spend in the specified period.
Name
spendingPeriod
Type
string
Description
Period for spending limit: 'daily', 'weekly', or 'monthly'.
Name
enableDocuments
Type
boolean
Description
Enable document processing capabilities.
Name
forceDocumentsUse
Type
boolean
Description
Require all requests to use document processing.
Name
logDocumentsResults
Type
boolean
Description
Log results from document processing operations.
Name
disabled
Type
boolean
Description
Temporarily disable the connection.

API Reference

POST/v1/management/connections

Create Connection

Create a new connection in your organization. Use this to set up a new configuration for API access with specific logging, spending, and document handling settings.

Required Fields

Name
name
Type
string
Description
A friendly name for your connection. Must be unique within your organization.

Optional Fields

Name
logRequestBody
Type
boolean
Description
Whether to log request bodies for auditing.
Name
logResponseBody
Type
boolean
Description
Whether to log response bodies for auditing.
Name
enableSpendingLimit
Type
boolean
Description
Enable spending limits for this connection.
Name
spendingLimit
Type
decimal
Description
Maximum amount allowed to spend.
Name
spendingPeriod
Type
string
Description
Period for spending limit: 'daily', 'weekly', or 'monthly'.
Name
enableDocuments
Type
boolean
Description
Enable document processing capabilities.
Name
forceDocumentsUse
Type
boolean
Description
Require all requests to use document processing.
Name
logDocumentsResults
Type
boolean
Description
Log results from document processing operations.

Request

POST

/v1/management/connections

curl -X POST https://api.usageguard.com/v1/management/connections \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}" \
  -d '{
    "name": "Production OpenAI",
    "logRequestBody": true,
    "logResponseBody": false,
    "enableSpendingLimit": true,
    "spendingLimit": 1000.00,
    "spendingPeriod": "monthly",
    "enableDocuments": true
  }'

Response

{
  "connectionId": "conn_abc123",
  "name": "Production OpenAI",
  "created": 1678901234
}

400: Bad Request

{
  "error": "Bad Request",
  "message": "Invalid request body: name is required"
}

401: Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

500: Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

PUT/v1/management/connections/{id}

Update Connection

Update an existing connection's settings. Use this to modify logging preferences, spending limits, or document handling settings.

Update endpoint supports partial updates - only include the fields you want to change.

Required Parameters

Name
id
Type
string
Description
The unique identifier of the connection to update.

Optional Fields

Name
name
Type
string
Description
A new name for the connection. Must be unique within your organization.
Name
logRequestBody
Type
boolean
Description
Whether to log request bodies for auditing.
Name
logResponseBody
Type
boolean
Description
Whether to log response bodies for auditing.
Name
enableSpendingLimit
Type
boolean
Description
Enable spending limits for this connection.
Name
spendingLimit
Type
decimal
Description
Maximum amount allowed to spend.
Name
spendingPeriod
Type
string
Description
Period for spending limit: 'daily', 'weekly', or 'monthly'.
Name
enableDocuments
Type
boolean
Description
Enable document processing capabilities.
Name
forceDocumentsUse
Type
boolean
Description
Require all requests to use document processing.
Name
logDocumentsResults
Type
boolean
Description
Log results from document processing operations.
Name
disabled
Type
boolean
Description
Temporarily disable the connection.

Request

PUT

/v1/management/connections/{id}

curl -X PUT https://api.usageguard.com/v1/management/connections/conn_abc123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}" \
  -d '{
    "name": "Production GPT-4",
    "enableSpendingLimit": true,
    "spendingLimit": 2000.00,
    "spendingPeriod": "monthly"
  }'

Response

{
  "connectionId": "conn_abc123",
  "name": "Production GPT-4",
  "updated": 1678901234
}

400: Bad Request

{
  "error": "Bad Request",
  "message": "Invalid spending period. Must be one of: daily, weekly, monthly"
}

404: Not Found

{
  "error": "Not Found",
  "message": "Connection not found"
}

DELETE/v1/management/connections/{id}

Delete Connection

Permanently delete a connection. Warning: This action cannot be undone. Make sure to backup any important configuration before deletion.

Required Parameters

Name
id
Type
string
Description
The unique identifier of the connection to delete.

Request

DELETE

/v1/management/connections/{id}

curl -X DELETE https://api.usageguard.com/v1/management/connections/conn_abc123 \
  -H "Authorization: Bearer {token}" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}"

204: No Content

{
  "status": "success"
}

404: Not Found

{
  "error": "Not Found",
  "message": "Connection not found"
}

403: Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions to delete this connection"
}

GET/v1/management/connections/{id}

Get Connection

Retrieve detailed information about a specific connection. Use this to get the current settings and status of your connection.

Required Parameters

Name
id
Type
string
Description
The unique identifier of the connection you want to retrieve.

Request

GET

/v1/management/connections/{id}

curl -X GET https://api.usageguard.com/v1/management/connections/conn_abc123 \
  -H "Authorization: Bearer {token}" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}"

Response

{
  "connectionId": "conn_abc123",
  "name": "Production OpenAI",
  "logRequestBody": true,
  "logResponseBody": false,
  "enableSpendingLimit": true,
  "spendingLimit": 1000.00,
  "spendingPeriod": "monthly",
  "enableDocuments": true,
  "forceDocumentsUse": false,
  "logDocumentsResults": true,
  "disabled": false,
  "updated": 1678901234,
  "created": 1678901234
}

404: Not Found

{
  "error": "Not Found",
  "message": "Connection not found"
}

GET/v1/management/connections

List Connections

Retrieve a list of all connections in your organization. Use this to view and manage your connections or to find specific connection IDs.

Query Parameters

Name
page
Type
integer
Description
Page number for pagination. Defaults to 1.
Name
pageSize
Type
integer
Description
Number of items per page. Defaults to 10.

Request

GET

/v1/management/connections

curl -X GET https://api.usageguard.com/v1/management/connections?page=1&pageSize=10 \
  -H "Authorization: Bearer {token}" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}"

Response

{
  "items": [
    {
      "connectionId": "conn_abc123",
      "name": "Production OpenAI",
      "disabledModelIdentifiersList": ["gpt-4"],
      "logRequestBody": true,
      "logResponseBody": false,
      "enableSpendingLimit": true,
      "spendingLimit": 1000.00,
      "spendingPeriod": "monthly",
      "enableDocuments": true,
      "forceDocumentsUse": false,
      "logDocumentsResults": true,
      "disabled": false,
      "updated": 1678901234,
      "created": 1678901234
    }
  ],
  "page": 1,
  "pageSize": 10,
  "totalCount": 1
}

401: Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

403: Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

500: Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}