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
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
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"
}
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
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 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
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 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
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"
}
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
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"
}