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.

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

Was this page helpful?