API Endpoints

Providers

List Providers

GET https://trybricks.ai/api/v1/providers

Response

[
  {
    "name": "Some descriptive name for the provider",
    "id": "some-provider-id",
    "createdAt": 1707864319,
    "updatedAt": 1707864319,
    "provider": "openai",
    "allowedModels": [] // Not used yet, can be ignored
  }
]

Proxy Secret Keys

Fetch all Proxy Secret Keys

GET https://trybricks.ai/api/v1/secret-keys?includeMetrics=true&start=<start>&end=<end>

Search parameters

warning

Setting includeMetrics to true will significantly slow down the request. If you don't need real-time usage, consider using the /v1/reporting/events-by-day endpoint.

Parameter	Required	Description
includeMetrics	optional	boolean, if set to true, response will include real-time usage metrics
start	required if includeMetrics is true	number, start time in seconds since epoch
end	required if includeMetrics is true	number, end time in seconds since epoch

Response

[
  {
    "name": "Some descriptive name for the key",
    "keyId": "some-key-id", // Unique identifier of the key
    "tags": ["clskya3uu0005ye8ggt5bp775"], // Organization ID
    "createdAt": 1708065781,
    "updatedAt": 1708065781,
    "revoked": false,
    "revokedReason": "",
    "costLimitInUsd": 100, // Cost limit over lifetime
    "costLimitInUsdOverTime": 100, // Cost limit per time unit
    "costLimitInUsdUnit": "mo", // Cost limit time unit
    "rateLimitOverTime": 10, // Rate limit per time unit
    "rateLimitUnit": "h", // Rate limit time unit
    "ttl": "1h", // Time to live
    "settingIds": ["some-provider-id"],
    "shouldLogRequest": false, // Whether to request body is logged by BricksAI
    "shouldLogResponse": false, // weather response body is logged by BricksAI
    "metrics": {
      // metrics of the secret key between `start` and `end`
      "numberOfRequests": 0,
      "successCount": 0,
      "costInUsd": 0,
      "latencyInMs": 0,
      "promptTokenCount": 0,
      "completionTokenCount": 0
    }
  }
]

Fetch one Proxy Secret Key

GET https://trybricks.ai/api/v1/secret-keys/:keyId?includeMetrics=true&start=<start>&end=<end>&increment=<increment>

Search parameters

warning

Setting includeMetrics to true will significantly slow down the request. If you don't need real-time usage, consider using the /v1/reporting/events-by-day endpoint.

Parameter	Required	Description
includeMetrics	optional	boolean, if set to true, response will include real-time usage metrics as a time series
start	required if includeMetrics is true	number, start time in seconds since epoch
end	required if includeMetrics is true	number, end time in seconds since epoch
increment	required if includeMetrics is true	number, increment between each data point in the time series in seconds

Response

[
  {
    "name": "Some descriptive name for the key",
    "keyId": "some-key-id", // Unique identifier of the key
    "tags": ["clskya3uu0005ye8ggt5bp775"], // Organization ID
    "key": "hashed-version-of-the-key", // Hashed value of the proxy secret key, can be ignored
    "createdAt": 1708065781,
    "updatedAt": 1708065781,
    "revoked": false,
    "revokedReason": "",
    "costLimitInUsd": 100, // Cost limit over lifetime
    "costLimitInUsdOverTime": 100, // Cost limit per time unit
    "costLimitInUsdUnit": "mo", // Cost limit time unit
    "rateLimitOverTime": 10, // Rate limit per time unit
    "rateLimitUnit": "h", // Rate limit time unit
    "ttl": "1h", // Time to live
    "settingIds": ["some-provider-id"],
    "shouldLogRequest": false, // Whether to request body is logged by BricksAI
    "shouldLogResponse": false, // weather response body is logged by BricksAI
    "dataPoints": [
      // A time series of metrics
      {
        "timeStamp": 1706774400, // Time in seconds since epoch
        "numberOfRequests": 1, // Number of requests during this increment
        "successCount": 1, // Number of successful requests during this increment
        "costInUsd": 100, // Cost of requests during this increment
        "latencyInMs": 722, // Median latency during this increment
        "promptTokenCount": 18, // Number of prompt tokens during this increment
        "completionTokenCount": 9 // Number of completion tokens during this increment
      }
    ],
    "latencyInMsMedian": 722, // Median latency over the entire time period
    "latencyInMs99th": 722 // 99th percentile latency over the entire time period
  }
]

Create a Proxy Secret Key

POST https://trybricks.ai/api/v1/secret-keys

Request body

{
  "name": "Some name", // Required, some descriptive name for the key
  "providerSettingIds": ["some-provider-id"], // Required, specify which provider settings this key has access to
  "ttl": "1h", // Optional, time to live, must be a positive integer followed by s, m, or h
  "rateLimitOverTime": 10, // Optional, rate limit per time unit, as specified in "rateLimitUnit"
  "rateLimitUnit": "h", // Optional, rate limit time unit, must be s, m, or h
  "costLimitInUsdPerMonth": 100, // Optional, cost limit per month
  "costLimitInUsdLifetime": 100 // Optional, cost limit over lifetime
  "keyRetrievalMethod": "ONCE" // Optional, value can be "ONCE" (default), "ONCE_PER_VIEWER", or "ANYTIME_BY_VIEWER". See more details below.
}

info

keyRetrievalMethod controls how the key can be retrieved from the UI after its creation. This setting cannot be edited later. See more details here

Response

{
  "id": "some-key-id", // Unique identifier of the key
  "name": "Some name",
  "organizationId": "some-organization-id",
  "key": "some-proxy-secret-key" // Proxy secret key, make sure to store it securely as you won't see it again
}

Update a Proxy Secret Key

info

Updates are not immedately effective. It may take a few seconds for the changes to take effect.

PATCH https://trybricks.ai/api/v1/secret-keys/[keyId]

Request body

{
  "name": "Some name", // Optional, some descriptive name for the key
  "providerSettingIds": ["some-provider-id"], // Optional, specify which provider settings this key has access to
  "revoked": true // Optional, whether the key is revoked
  "rateLimitOverTime": 10, // Optional, rate limit per time unit, as specified in "rateLimitUnit"
  "rateLimitUnit": "h", // Optional, rate limit time unit, must be s, m, or h
  "costLimitInUsdPerMonth": 100, // Optional, cost limit per month
  "costLimitInUsdLifetime": 100 // Optional, cost limit over lifetime
}

Response

success

Proxy Secret Keys Usage

Fetch Proxy Secret Keys Usage

warning

This endpoint returns real-time usage, but is computationally expensive. If you don't need real-time usage and need a faster response, consider using the /v1/reporting/events-by-day endpoint.

POST https://trybricks.ai/api/v1/reporting/events

Request body

{
  "start": 1710460800, // Required, start time in seconds since epoch
  "end": 1711492257, // Required, end time in seconds since epoch
  "increment": 300, // Required, increment between each data point in the time series in seconds
  "keyIds": ["some-key-id"] // Required, list of key IDs
  "customIds": ["some-custom-id"] // Optional, list of custom IDs
  "groupBy": ["keyId", "customId", "model"] // Optional, a list of fields to group by. Must be one of "keyId", "customId", or "model". If not specified, the usage will be aggregated across all keys, custom IDs, and models.
}

Response

Each object in dataPoints represents usage for an increment.

{
	"dataPoints": [
		{
			"timeStamp": 1710460800,
			"numberOfRequests": 123,
			"successCount": 123,
			"costInUsd": 123,
			"latencyInMs": 123,
			"promptTokenCount": 123,
			"completionTokenCount": 123,
			"model": "",
			"keyId": "some-key-id"
      "customId": "some-custom-id"
		},
		...
	],
	"latencyInMsMedian": 0,
	"latencyInMs99th": 0
}

Fetch Proxy Secret Keys Usage by Day

info

This is the fastest endpoint for fetching usage metrics. However, metrics from this endpoint are only updated every 24 hours. If you need real-time data, use the slower /v1/secret-keys/:keyId, /v1/secret-keys, or /v1/reporting/events endpoints instead.

POST https://trybricks.ai/api/v1/reporting/events-by-day

Request body

{
  "start": 1710460800, // Start time in seconds since epoch
  "end": 1711492257, // End time in seconds since epoch
  "keyIds": ["some-key-id"] // List of key IDs
}

Response

Each object in dataPoints represents a key's usage for a day. If a key does not have any usage for the day, it will not be included in the response.

{
	"dataPoints": [
		{
			"timeStamp": 1710460800,
			"numberOfRequests": 123,
			"successCount": 123,
			"costInUsd": 123,
			"latencyInMs": 123,
			"promptTokenCount": 123,
			"completionTokenCount": 123,
			"model": "",
			"keyId": "some-key-id"
		},
		...
	],
	"latencyInMsMedian": 0, // ignore
	"latencyInMs99th": 0 // ignore
}

Custom IDs

List Custom IDs by Proxy Secret Key

This endpoint returns a list of Custom IDs that were used with a proxy secret key.

GET https://trybricks.ai/api/v1/custom-ids?keyId=<some-key-id>

Query parameters

Parameter	Required	Description
keyId	required	ID of proxy secret key that you want to query

Response

{
  "customIds": ["id-1", "id-2", "id-3"]
}

Users

Get all users in an organization

GET https://trybricks.ai/api/v1/users

Response

[
  {
    "id": "65853dc9-0c3f-4b6c-ad2a-edec29b7d36c",
    "userId": "some-user-id",
    "name": "John Doe",
    "createdAt": 1721626167,
    "updatedAt": 1721626167,
    "tags": ["clusvayv40005lm3igc18ajru"],
    "revoked": false,
    "revokedReason": "",
    "costLimitInUsd": 0,
    "costLimitInUsdOverTime": 0,
    "costLimitInUsdUnit": "",
    "rateLimitOverTime": 0,
    "rateLimitUnit": "",
    "ttl": ""
  }
]

Get one user by user ID

GET https://trybricks.ai/api/v1/users/<userId>

Response

{
  "id": "65853dc9-0c3f-4b6c-ad2a-edec29b7d36c",
  "userId": "<userId>",
  "name": "John Doe",
  "createdAt": 1721626167,
  "updatedAt": 1721626167,
  "tags": ["clusvayv40005lm3igc18ajru"],
  "revoked": false,
  "revokedReason": "",
  "costLimitInUsd": 0,
  "costLimitInUsdOverTime": 0,
  "costLimitInUsdUnit": "",
  "rateLimitOverTime": 0,
  "rateLimitUnit": "",
  "ttl": ""
}

Create a user

POST https://trybricks.ai/api/v1/users

Request body

{
  "userId": "some-user-id", // optional, if not provided, BricksAI will generate a random ID for you
  "name": "John Doe", // required
  "ttl": "never", // required, must be one of "never" | "24h" | "168h" | "720h"
  "rateLimitOverTime": 10, // optional
  "rateLimitUnit": "s", // optional, must be one of "s" | "m" | "h"
  "costLimitInUsd": 100, // optional, cost limit over lifetime
  "costLimitInUsdOverTime": 100, // optional, cost limit per month
  "costLimitInUsdUnit": "mo" // optional, must be set to "mo"
}

Response

{
  "id": "65853dc9-0c3f-4b6c-ad2a-edec29b7d36c",
  "userId": "some-user-id",
  "name": "John Doe",
  "createdAt": 1721626167,
  "updatedAt": 1721626167,
  "tags": ["clusvayv40005lm3igc18ajru"],
  "revoked": false,
  "revokedReason": "",
  "costLimitInUsd": 100,
  "costLimitInUsdOverTime": 100,
  "costLimitInUsdUnit": "mo",
  "rateLimitOverTime": 10,
  "rateLimitUnit": "s",
  "ttl": ""
}

Revoke a user

PATCH https://trybricks.ai/api/v1/users/<userId>

Request body

{
  "revoked": true // required
}

Response

{
  "id": "65853dc9-0c3f-4b6c-ad2a-edec29b7d36c",
  "userId": "some-user-id",
  "name": "John Doe",
  "createdAt": 1721626167,
  "updatedAt": 1721626167,
  "tags": ["clusvayv40005lm3igc18ajru"],
  "revoked": true,
  "revokedReason": "",
  "costLimitInUsd": 100,
  "costLimitInUsdOverTime": 100,
  "costLimitInUsdUnit": "mo",
  "rateLimitOverTime": 10,
  "rateLimitUnit": "s",
  "ttl": ""
}