> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airctrl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK methods

> Complete public capability reference for AirctrlClient.

export function AirctrlWordmark() {
  return <span className="airctrl-wordmark" aria-label="AIRCTRL">
      <span aria-hidden="true" className="airctrl-wordmark-air">AIR</span>
      <span aria-hidden="true" className="airctrl-wordmark-ctrl">CTRL</span>
    </span>;
}

All methods below belong to `AirctrlClient`. Method names are the stable developer bindings verified against the public API.

For a runnable TypeScript example of every method, continue to [SDK examples](/sdk/examples).

## Identity availability

A human PAT may call every method on this page when RBAC permits it. A Service Account may call only:

* `listRecords()` and `listProjectRecords()`.
* `getSecret()`, `readRecord()` and `getAll()`.
* `listProviders()`.
* `getGateway()`, `listGatewayTokens()`, `listGatewayLogs()`, `getGatewayLogDetail()` and
  `listGatewayKeyAccess()`.

Every other method is human-only. The SDK does not turn a human-only API operation into a Service
Account operation. RBAC and record key access can further reduce what either identity may do.

## Context and projects

| Method                                                       | Purpose                                                      |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| `listAccounts()`                                             | List accounts the authenticated human can access.            |
| `listProjects({ accountId, includeArchived? })`              | List accessible projects in one account.                     |
| `getProject(projectId, { accountId })`                       | Read one project or return `null`.                           |
| `createProject(input)`                                       | Create a project and make the creator Project Administrator. |
| `updateProject(projectId, input, { accountId })`             | Replace project name, description and active state.          |
| `setProjectArchiveState(projectId, archived, { accountId })` | Archive or restore a project.                                |

## Record reading and creation

| Method                                                           | Purpose                                                                               |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `listRecords(input?)`                                            | List record metadata across accessible account scope.                                 |
| `listProjectRecords(projectId, input?)`                          | List metadata for one project.                                                        |
| `getSecret({ recordId, vaultPassword? })`                        | Decrypt one complete record locally.                                                  |
| `readRecord({ recordId, scope?, environment?, vaultPassword? })` | Read selected record sections and decrypt fields when requested.                      |
| `getAll({ projectId, vaultPassword?, audit? })`                  | Decrypt every accessible record in one project.                                       |
| `createSecret(input)`                                            | Encrypt and create a record from supplied fields. Human mode only.                    |
| `createGeneratedRecord(input)`                                   | Generate supported material locally, encrypt it and create a record. Human mode only. |
| `setSecret(input)`                                               | Update by record ID or upsert by project, name and format. Human mode only.           |

## Record lifecycle and sharing

| Method                                                       | Purpose                                                            |
| ------------------------------------------------------------ | ------------------------------------------------------------------ |
| `updateRecordMetadata(recordId, patch)`                      | Change name, tags, due date or rotation interval.                  |
| `setRecordArchiveState(recordId, archived)`                  | Archive or restore a record.                                       |
| `transferRecordOwnership(recordId, userId)`                  | Transfer ownership to another eligible user.                       |
| `getRecordVersions(recordId)`                                | List encrypted version history.                                    |
| `rollbackRecordToVersion(recordId, versionId)`               | Restore an earlier version as the new current version.             |
| `rotateRecord({ recordId, vaultPassword })`                  | Rotate the record data key and encrypted value.                    |
| `shareRecordWithUser(input)`                                 | Encrypt the record key for one user and grant access.              |
| `shareRecordWithServiceAccount(input)`                       | Encrypt the record key for one Service Account and grant access.   |
| `shareRecordWithGroup(input)`                                | Encrypt the record key for current group members and grant access. |
| `revokeRecordFromUser(recordId, userId)`                     | Remove one user grant and wrapper.                                 |
| `revokeRecordFromServiceAccount(recordId, serviceAccountId)` | Remove one Service Account grant and wrapper.                      |
| `revokeRecordFromGroup(recordId, groupId)`                   | Remove a group grant and its wrappers.                             |

## Record history and audit

| Method                             | Purpose                                  |
| ---------------------------------- | ---------------------------------------- |
| `getRecordAudit(recordId, limit?)` | Read recent audit events for one record. |
| `listRecordAnomalies(scope)`       | List unusual record events.              |
| `listRecordActivity(day, scope)`   | Read daily record activity.              |
| `listRecordAlerts(input)`          | Read the paginated record alert feed.    |
| `listRecordAccess(input)`          | Read the paginated record access feed.   |

## Providers and gateways

| Method                                                                     | Purpose                                                                                                  |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `listProviders()`                                                          | List enabled AI providers.                                                                               |
| `listProviderCredentials(accountId)`                                       | List safe provider credential metadata.                                                                  |
| `createProviderCredential(input)`                                          | Validate, encrypt and store a provider credential.                                                       |
| `listProviderCredentialModels(id, { accountId })`                          | Read the credential's live catalog, capability tags, supported capabilities and `airctrlSupport` status. |
| `rotateProviderCredential(id, apiKey, { accountId })`                      | Replace a provider credential value.                                                                     |
| `updateProviderCredentialLabel(id, label, { accountId })`                  | Rename a provider credential.                                                                            |
| `revokeProviderCredential(id, { accountId })`                              | Revoke a provider credential.                                                                            |
| `listGateways(projectId)`                                                  | List gateways in one project.                                                                            |
| `getGateway(gatewayId)`                                                    | Read one gateway and its settings.                                                                       |
| `createGateway(input)`                                                     | Create a gateway and optionally attach credentials.                                                      |
| `updateGateway(gatewayId, patch, { accountId })`                           | Update editable gateway details.                                                                         |
| `deleteGateway(gatewayId, { accountId })`                                  | Disable a gateway and revoke its tokens.                                                                 |
| `updateGatewaySettings(gatewayId, patch, { accountId })`                   | Update limits, logging, guardrails, caching or models.                                                   |
| `attachGatewayCredential(gatewayId, credentialId, modelId, { accountId })` | Validate a model against the credential's live catalog and attach that exact key/model binding.          |
| `detachGatewayCredential(gatewayId, credentialId, { accountId })`          | Detach a provider credential without revoking it.                                                        |

## Gateway tokens

| Method                                                        | Purpose                                           |
| ------------------------------------------------------------- | ------------------------------------------------- |
| `listGatewayTokens(gatewayId)`                                | List safe token metadata.                         |
| `createGatewayToken(gatewayId, input, { accountId })`         | Create a gateway token and return its value once. |
| `renameGatewayToken(gatewayId, tokenId, name, { accountId })` | Change the token display name.                    |
| `revokeGatewayToken(gatewayId, tokenId, { accountId })`       | Stop the token from authenticating.               |
| `deleteGatewayToken(gatewayId, tokenId, { accountId })`       | Delete token metadata.                            |

## Gateway observability

| Method                                                     | Purpose                                                    |
| ---------------------------------------------------------- | ---------------------------------------------------------- |
| `listGatewayLogs(gatewayId, input?)`                       | List request metadata for one gateway.                     |
| `getGatewayLogDetail(gatewayId, logId)`                    | Read stored request and response bodies.                   |
| `listGatewayKeyAccess(gatewayId, input?)`                  | List provider credential access outcomes.                  |
| `listUsageLogs(input)`                                     | List usage across project gateways.                        |
| `getUsageLogDetail(projectId, logId)`                      | Read one project usage log body.                           |
| `getUsageSpend(projectId)`                                 | Compare spend with effective limits.                       |
| `getUsageMetrics(projectId, input?)`                       | Read request, error, token, latency and spend metrics.     |
| `getGatewayOtelExport(gatewayId, { accountId })`           | Read safe OpenTelemetry export settings.                   |
| `updateGatewayOtelExport(gatewayId, patch, { accountId })` | Update OpenTelemetry metrics, traces, endpoint or headers. |

## Service Account metadata

| Method                                               | Purpose                                    |
| ---------------------------------------------------- | ------------------------------------------ |
| `listServiceAccounts({ accountId })`                 | List safe Service Account metadata.        |
| `getServiceAccount(serviceAccountId, { accountId })` | Find one Service Account or return `null`. |

These metadata methods require a human PAT. Service Account creation, lifecycle, credential administration and identity rotation are not public SDK capabilities. The package contains internal Web infrastructure for those flows, but it is not part of this developer contract.

## Exact method signatures

Optional values end with `?`. Input types are exported by `@airctrl/sdk`, so your editor can show every
field and accepted value.

```ts Context and projects theme={}
listAccounts()
listProjects(input: ListProjectsInput)
getProject(projectId: string, options: { accountId: string })
createProject(input: CreateProjectInput)
updateProject(projectId: string, input: UpdateProjectInput, options: { accountId: string })
setProjectArchiveState(projectId: string, archived: boolean, options: { accountId: string })
```

```ts Records theme={}
listRecords(input: ListRecordsInput = {})
listProjectRecords(projectId: string, input: ListProjectRecordsInput = {})
getSecret(params: { recordId: string; vaultPassword?: string; audit?: boolean })
readRecord(params: { recordId: string; vaultPassword?: string; scope?: string[]; environment?: string; audit?: boolean })
getAll(params?: { projectId?: string; vaultPassword?: string; audit?: boolean })
createSecret(params: CreateSecretInput & { vaultPassword?: string })
createGeneratedRecord(params: CreateGeneratedRecordInput & { vaultPassword?: string })
setSecret(input: SetSecretInput)
updateRecordMetadata(recordId: string, patch: UpdateRecordMetadataInput)
setRecordArchiveState(recordId: string, archived: boolean)
transferRecordOwnership(recordId: string, newOwnerUserId: string)
getRecordVersions(recordId: string)
getRecordAudit(recordId: string, limit = 100)
rollbackRecordToVersion(recordId: string, targetVersionId: string)
rotateRecord(params: { recordId: string; vaultPassword?: string })
shareRecordWithUser(params: { recordId: string; granteeUserId: string; permission?: 'view' | 'read'; vaultPassword?: string })
shareRecordWithServiceAccount(params: { accountId: string; recordId: string; serviceAccountId: string; vaultPassword?: string })
shareRecordWithGroup(params: { recordId: string; groupId: string; vaultPassword?: string })
revokeRecordFromUser(recordId: string, granteeUserId: string)
revokeRecordFromServiceAccount(recordId: string, serviceAccountId: string)
revokeRecordFromGroup(recordId: string, groupId: string)
listRecordAnomalies(input: RecordAuditScope = {})
listRecordActivity(day: string, input: RecordAuditScope = {})
listRecordAlerts(input: RecordAuditScope & { limit?: number; offset?: number } = {})
listRecordAccess(input: RecordAuditScope & { limit?: number; offset?: number; actions?: string[] } = {})
```

```ts Providers and gateways theme={}
listProviders()
listProviderCredentials(accountId: string)
createProviderCredential(input: CreateProviderCredentialInput)
listProviderCredentialModels(credentialId: string, options?: { accountId?: string })
rotateProviderCredential(credentialId: string, apiKey: string, options?: { accountId?: string })
updateProviderCredentialLabel(credentialId: string, label: string, options?: { accountId?: string })
revokeProviderCredential(credentialId: string, options?: { accountId?: string })
listGateways(projectId: string)
getGateway(gatewayId: string)
createGateway(input: CreateGatewayInput)
updateGateway(gatewayId: string, patch: UpdateGatewayInput, options?: { accountId?: string })
deleteGateway(gatewayId: string, options?: { accountId?: string })
attachGatewayCredential(gatewayId: string, credentialId: string, modelId: string, options?: { accountId?: string })
detachGatewayCredential(gatewayId: string, credentialId: string, options?: { accountId?: string })
updateGatewaySettings(gatewayId: string, patch: UpdateGatewaySettingsInput, options?: { accountId?: string })
listGatewayTokens(gatewayId: string)
createGatewayToken(gatewayId: string, input: CreateGatewayTokenInput, options?: { accountId?: string })
renameGatewayToken(gatewayId: string, tokenId: string, name: string, options?: { accountId?: string })
revokeGatewayToken(gatewayId: string, tokenId: string, options?: { accountId?: string })
deleteGatewayToken(gatewayId: string, tokenId: string, options?: { accountId?: string })
listGatewayLogs(gatewayId: string, input: ListGatewayLogsInput = {})
getGatewayLogDetail(gatewayId: string, logId: string)
listGatewayKeyAccess(gatewayId: string, input: ListGatewayKeyAccessInput = {})
listUsageLogs(input: ListUsageLogsInput)
getUsageLogDetail(projectId: string, logId: string)
getUsageSpend(projectId: string)
getUsageMetrics(projectId: string, input: { since?: string; bucket?: UsageBucket } = {})
getGatewayOtelExport(gatewayId: string, options?: { accountId?: string })
updateGatewayOtelExport(gatewayId: string, patch: UpdateOtelExportInput, options?: { accountId?: string })
```

```ts Service Account metadata theme={}
listServiceAccounts(options: { accountId: string })
getServiceAccount(serviceAccountId: string, options: { accountId: string })
```

## Input and result rules

* IDs are UUID strings. Keep account, project, record, gateway, token and credential IDs separate.
* Methods with `accountId` select the active account. The value never grants access.
* List methods return arrays or paginated objects. Empty access returns an empty result, not broader data.
* `getProject()` and `getServiceAccount()` can return `null` when the resource is unavailable.
* Write methods that create a resource return its new identifier or resource metadata.
* Methods that return no resource resolve successfully without a value.
* Record plaintext is accepted or returned only by client-side crypto methods. Raw HTTP methods work with encrypted material.
* Provider secrets and newly created gateway tokens are one-time values. Do not log their result.

## End-to-end examples

Create a project, then create an encrypted record inside it:

```ts theme={}
const project = await airctrl.createProject({
  accountId,
  name: 'Payments',
  description: 'Credentials for the payments service',
})

const record = await airctrl.createSecret({
  projectId: project.project_id,
  name: 'Database URL',
  secretFormat: 'plain',
  fieldValues: { body: process.env.SOURCE_DATABASE_URL! },
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
})
```

Read only metadata first, then decrypt only when the process needs the value:

```ts theme={}
const records = await airctrl.listProjectRecords(projectId)
const selected = records.find((record) => record.name === 'Database URL')

if (!selected) throw new Error('Record not found')

const secret = await airctrl.getSecret({
  recordId: selected.record_id,
  vaultPassword: process.env.AIRCTRL_VAULT_PASSPHRASE!,
  audit: true,
})
```

Create a gateway token and display the one-time value only to the custody step:

```ts theme={}
const token = await airctrl.createGatewayToken(
  gatewayId,
  {
    name: 'Payments development',
    scopes: ['run', 'read_logs'],
    expiresInDays: 30,
    allowedModels: ['gpt-5.4-mini'],
  },
  { accountId },
)

await custody.write(token.plaintext)
```

Read project-wide usage without requesting stored request bodies:

```ts theme={}
const [metrics, spend] = await Promise.all([
  airctrl.getUsageMetrics(projectId, { bucket: 'day' }),
  airctrl.getUsageSpend(projectId),
])
```

## Failure behavior

Every API failure throws `AirctrlError`. Inspect its fields instead of parsing prose.

| Field     | Meaning                                          |
| --------- | ------------------------------------------------ |
| `status`  | HTTP status returned by <AirctrlWordmark />.     |
| `code`    | Stable error category when the API provides one. |
| `message` | Specific reason for the failure.                 |
| `details` | Optional validation or conflict details.         |

```ts theme={}
try {
  await airctrl.updateRecordMetadata(recordId, { name: '' })
} catch (error) {
  if (!(error instanceof AirctrlError)) throw error

  if (error.status === 400) {
    console.error('Fix the submitted metadata', error.details)
  } else if (error.status === 403) {
    console.error('The current identity cannot perform this action', error.code)
  } else {
    throw error
  }
}
```

Do not retry `400`, `403`, or `404` unchanged. Retry temporary `429`, `500`, or `503` failures with
bounded exponential backoff. Reuse the same idempotency key only for the same intended write.