SDK methods - AIRCTRL

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.

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.

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.

Context and projects

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

Records

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[] } = {})

Providers and gateways

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

Service Account metadata

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:

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:

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:

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:

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 .
`code`	Stable error category when the API provides one.
`message`	Specific reason for the failure.
`details`	Optional validation or conflict details.

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.

​Identity availability

​Context and projects

​Record reading and creation

​Record lifecycle and sharing

​Record history and audit

​Providers and gateways

​Gateway tokens

​Gateway observability

​Service Account metadata

​Exact method signatures

​Input and result rules

​End-to-end examples

​Failure behavior

Identity availability

Context and projects

Record reading and creation

Record lifecycle and sharing

Record history and audit

Providers and gateways

Gateway tokens

Gateway observability

Service Account metadata

Exact method signatures

Input and result rules

End-to-end examples

Failure behavior