API by area

Your account and API keys

83 endpoints. Paths are relative to https://api.sandscale.dev; values in braces are ones you fill in.

API reference · Authentication · Errors

MethodPathWhat it does
GET/api/v1/account/api-keysList api keys
POST/api/v1/account/api-keysCreate an api key
DELETE/api/v1/account/api-keys/{id}Delete one api key
POST/api/v1/account/api-keys/{id}/rotateRotate an api key
GET/api/v1/account/console-preferencesList console preferences
PUT/api/v1/account/console-preferencesSet console preferences
GET/api/v1/account/devicesList devices
POST/api/v1/account/devicesCreate a device
POST/api/v1/account/devices/{deviceId}/revokeRevoke a device
POST/api/v1/account/emailCreate an email
GET/api/v1/account/invitationsThe pending invitations sent to the signed-in person's verified address, for information. None can be accepted from this list: accepting needs the invitation's token, which only its link carries.
POST/api/v1/account/invitations/acceptWith the invitation's token, the signed-in person joins the organization that invited their address, with the role the invitation gives.
POST/api/v1/account/invitations/lookupThe invitation of the token the person holds, when it is pending and was sent to their address (the console shows it before the person accepts).
GET/api/v1/account/organizationsList organizations
POST/api/v1/account/passwordCreate a password
GET/api/v1/account/profileList profile
PATCH/api/v1/account/profileUpdate profile
GET/api/v1/account/remembered-devicesList remembered devices
DELETE/api/v1/account/remembered-devicesDelete remembered devices
DELETE/api/v1/account/remembered-devices/{id}Delete one remembered device
GET/api/v1/account/resolve/{ref}Get one resolve
GET/api/v1/account/securityList security
GET/api/v1/account/security/checklistList checklist
GET/api/v1/account/sessionsList sessions
DELETE/api/v1/account/sessions/{id}Delete one session
POST/api/v1/account/sessions/revoke-othersCreate a revoke other
GET/api/v1/account/sign-in-alertsList sign in alerts
POST/api/v1/account/sign-in-alerts/{id}/confirmConfirm a sign in alert
POST/api/v1/account/sign-in-alerts/{id}/reportReport a sign in alert
GET/api/v1/account/sign-insList sign ins
GET/api/v1/account/ssh-keysList ssh keys
POST/api/v1/account/ssh-keysCreate a ssh key
DELETE/api/v1/account/ssh-keys/{keyID}Delete one ssh key
POST/api/v1/account/step-upCreate a step up
POST/api/v1/account/step-up-handoff/denyCreate a deny
POST/api/v1/account/step-up-handoff/lookupCreate a lookup
POST/api/v1/account/step-up-handoff/proofsCreate a proof
POST/api/v1/account/step-up/{id}/emailEmail a step up
POST/api/v1/account/step-up/{id}/handoffHandoff a step up
POST/api/v1/account/step-up/{id}/handoff/tokenCreate a token
POST/api/v1/account/step-up/{id}/proofsCreate a proof for a step up
GET/api/v1/me/access-requestsThe caller's own requests in their organization (never resource_access ones). Query: status (default all), limit (1-200), offset.
POST/api/v1/me/access-requestsCreate an access request
GET/api/v1/me/harnessReturns the signed pack chain that applies to the caller (GET /api/v1/me/harness). The service delivers only a chain whose every pack the caller may use (harness.packs:use): a more specific assignment with an unusable pack is passed over for the next one and listed in the response's skipped.
POST/api/v1/me/harness/eventsIs the user-authenticated harness activity ingest route (POST /api/v1/me/harness/events), rate-limited per user.
GET/api/v1/me/notification-settingsList notification settings
PUT/api/v1/me/notification-settingsSet notification settings
GET/api/v1/me/notificationsList notifications
POST/api/v1/me/notifications/{id}/readRead a notification
POST/api/v1/me/notifications/read-allCreate a read all
GET/api/v1/me/notifications/unread-countList unread count
GET/api/v1/me/observe/metricsThe caller's own series of the built-in namespaces only, since anyone with observe:write could put a custom series naming someone else's UserId with their values per period and the statistic over the whole window, all computed here. Query parameters: Namespace, Stat (default Sum), Period in seconds (default 3600), StartTime and EndTime (RFC 3339, default the last 24 hours).
GET/api/v1/me/permissionsList permissions
GET/api/v1/me/policiesList policies
GET/api/v1/me/sessionsList sessions
GET/api/v1/me/usageList usage
GET/api/v1/notifications/unsubscribeList unsubscribe
POST/api/v1/notifications/unsubscribeCreate an unsubscribe
POST/api/v1/passkeys/register/beginCreate a begin
POST/api/v1/passkeys/register/completeCreate a complete
GET/api/v1/privacy/dsarOne's own requests.
POST/api/v1/privacy/dsarA member files a request for themselves: the subject is always the signed-in person, with their account email.
POST/api/v1/privacy/dsar-exports/downloadThe export behind a valid signed link, recorded as downloaded. The link is the credential: it names one export and expires after ten minutes.
GET/api/v1/privacy/dsar/{id}One's own request.
POST/api/v1/privacy/dsar/{id}/exports/{exportID}/linkThe subject's own export.
GET/api/v1/sessions/{id}/budgetBudget of a session
POST/api/v1/sessions/{id}/budgetBudget a session
POST/api/v1/sessions/{id}/usageUsage a session
POST/api/v1/svc/account/CloseAccountClose account
POST/api/v1/svc/account/DeleteAlternateContactDelete alternate contact
POST/api/v1/svc/account/DisableRegionDisable region
POST/api/v1/svc/account/EnableRegionEnable region
POST/api/v1/svc/account/GetAccountInformationGet account information
POST/api/v1/svc/account/GetAlternateContactGet alternate contact
POST/api/v1/svc/account/GetContactInformationGet contact information
POST/api/v1/svc/account/GetRegionOptStatusGet region opt status
POST/api/v1/svc/account/ListRegionsList regions
POST/api/v1/svc/account/PutAccountNamePut account name
POST/api/v1/svc/account/PutAlternateContactPut alternate contact
POST/api/v1/svc/account/PutContactInformationPut contact information
POST/api/v1/svc/account/PutIamBillingAccessPut iam billing access
POST/api/v1/svc/account/ReopenAccountReopen account
POST/api/v1/svc/account/UpdateRootEmailUpdate root email

Endpoints

GET /api/v1/account/api-keys

List api keys

Permission
signed in
Response
200: object of any
Errors
401: unauthorized; 403: person_required; 503: unavailable

POST /api/v1/account/api-keys

Create an api key

Permission
signed in
Request body
personalKeyRequest
Response
201: personalKeyCreated
Errors
400: invalid_json, validation_error; 401: unauthorized; 403: person_required, regional_api_keys_unavailable; 415: content_type; 503: unavailable

DELETE /api/v1/account/api-keys/{id}

Delete one api key

Permission
signed in
Path parameters
id
Errors
401: unauthorized; 403: person_required; 503: unavailable

POST /api/v1/account/api-keys/{id}/rotate

Rotate an api key

Permission
signed in
Path parameters
id
Request body
personalRotateRequest
Response
200: personalKeyCreated
Errors
400: invalid_json; 401: unauthorized; 403: person_required, regional_api_keys_unavailable; 415: content_type; 503: unavailable

GET /api/v1/account/console-preferences

List console preferences

Permission
signed in
Response
200: ConsolePreferences
Errors
401: unauthorized; 403: forbidden

PUT /api/v1/account/console-preferences

Set console preferences

Permission
signed in
Request body
object
Response
200: ConsolePreferences
Errors
400: invalid_json, invalid_request; 401: unauthorized; 403: forbidden, role_session_read_only; 415: content_type

GET /api/v1/account/devices

List devices

Permission
signed in
Response
200: object of any
Errors
401: unauthorized

POST /api/v1/account/devices

Create a device

Permission
signed in
Request body
deviceHeartbeatRequest
Response
200: object of any
Errors
400: invalid_json; 401: unauthorized; 415: content_type

POST /api/v1/account/devices/{deviceId}/revoke

Revoke a device

Permission
signed in
Path parameters
deviceId
Errors
401: unauthorized

POST /api/v1/account/email

Create an email

Permission
signed in
Request body
object
Response
200: object of any
Errors
400: email_unavailable, invalid_invitation, invalid_json, invitation_email_mismatch, validation_error; 401: invalid_credentials, unauthorized; 403: registration_closed, role_session_refused, sso_required; 404: not_found; 409: conflict, contained, last_super_admin; 415: content_type; 422: failed_precondition

GET /api/v1/account/invitations

The pending invitations sent to the signed-in person's verified address, for information. None can be accepted from this list: accepting needs the invitation's token, which only its link carries.

Permission
signed in
Response
200: object of any
Errors
401: unauthorized; 403: email_not_verified, forbidden, operator_access_required; 404: invalid_invitation; 409: conflict, root_not_linked; 503: unavailable

POST /api/v1/account/invitations/accept

With the invitation's token, the signed-in person joins the organization that invited their address, with the role the invitation gives.

Permission
signed in
Response
200: AcceptedInvitation
Errors
400: invalid_json; 401: unauthorized; 403: email_not_verified, forbidden, operator_access_required; 404: invalid_invitation; 409: conflict, root_not_linked; 415: content_type; 503: unavailable

POST /api/v1/account/invitations/lookup

The invitation of the token the person holds, when it is pending and was sent to their address (the console shows it before the person accepts).

Permission
signed in
Response
200: UserInvitation
Errors
400: invalid_json; 401: unauthorized; 403: email_not_verified, forbidden, operator_access_required; 404: invalid_invitation; 409: conflict, root_not_linked; 415: content_type; 503: unavailable

GET /api/v1/account/organizations

List organizations

Permission
signed in
Response
200: object of any
Errors
401: unauthorized; 403: person_required; 503: unavailable

POST /api/v1/account/password

Create a password

Permission
signed in
Request body
object
Errors
400: invalid_json, validation_error; 401: unauthorized; 403: invalid_credentials; 415: content_type; 503: temporarily_unavailable

GET /api/v1/account/profile

List profile

Permission
signed in
Response
200: object of any
Errors
401: unauthorized; 403: role_session_refused; 404: not_found

PATCH /api/v1/account/profile

Update profile

Permission
signed in
Request body
object
Errors
400: invalid_json; 401: unauthorized; 403: role_session_refused; 415: content_type

GET /api/v1/account/remembered-devices

List remembered devices

Permission
api:access
Response
200: object of any
Errors
401: unauthorized; 403: person_required

DELETE /api/v1/account/remembered-devices

Delete remembered devices

Permission
api:access
Errors
401: unauthorized; 403: person_required; 404: not_found

DELETE /api/v1/account/remembered-devices/{id}

Delete one remembered device

Permission
api:access
Path parameters
id
Errors
401: unauthorized; 403: person_required; 404: not_found

GET /api/v1/account/resolve/{ref}

Get one resolve

Permission
signed in
Path parameters
ref
Response
200: ResolvedAccount
Errors
401: unauthorized; 404: not_found

GET /api/v1/account/security

List security

Permission
signed in
Response
200: object of any
Errors
401: unauthorized; 403: role_session_refused; 503: temporarily_unavailable

GET /api/v1/account/security/checklist

List checklist

Permission
api:access
Response
200: object of any
Errors
401: unauthorized; 403: person_required, role_session_refused; 503: temporarily_unavailable

GET /api/v1/account/sessions

List sessions

Permission
signed in
Response
200: object of any
Errors
401: unauthorized; 403: role_session_refused

DELETE /api/v1/account/sessions/{id}

Delete one session

Permission
signed in
Path parameters
id
Errors
401: unauthorized; 403: role_session_refused; 404: not_found

POST /api/v1/account/sessions/revoke-others

Create a revoke other

Permission
signed in
Errors
401: unauthorized; 403: role_session_refused

GET /api/v1/account/sign-in-alerts

List sign in alerts

Permission
api:access
Response
200: object of any
Errors
401: unauthorized; 403: person_required, role_session_refused; 503: temporarily_unavailable

POST /api/v1/account/sign-in-alerts/{id}/confirm

Confirm a sign in alert

Permission
api:access
Path parameters
id
Response
200: alertView
Errors
400: invalid_request; 401: unauthorized; 403: confirm_needs_earlier_session, person_required, role_session_refused; 404: not_found; 409: alert_reported; 413: invalid_request; 503: temporarily_unavailable

POST /api/v1/account/sign-in-alerts/{id}/report

Report a sign in alert

Permission
api:access
Path parameters
id
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized; 403: person_required, role_session_refused; 404: not_found; 409: alert_reported; 413: invalid_request; 503: temporarily_unavailable

GET /api/v1/account/sign-ins

List sign ins

Permission
api:access
Response
200: object of any
Errors
400: validation_error; 401: unauthorized; 403: person_required, role_session_refused; 409: no_account; 503: temporarily_unavailable

GET /api/v1/account/ssh-keys

List ssh keys

Permission
api:access
Response
200: object of any
Errors
401: unauthorized; 403: forbidden; 503: unavailable

POST /api/v1/account/ssh-keys

Create a ssh key

Permission
workspaces:create
Request body
addSSHKeyBody
Response
201: Key
Errors
400: invalid_json, validation_error; 401: unauthorized; 403: forbidden, person_required; 409: duplicate, too_many_keys; 415: content_type; 503: unavailable

DELETE /api/v1/account/ssh-keys/{keyID}

Delete one ssh key

Permission
workspaces:create
Path parameters
keyID
Errors
401: unauthorized; 403: forbidden, person_required; 404: not_found; 503: unavailable

POST /api/v1/account/step-up

Create a step up

Permission
api:access
Request body
elevationBeginRequest
Response
201: ElevationChallenge
Errors
400: invalid_json; 415: content_type

POST /api/v1/account/step-up-handoff/deny

Create a deny

Permission
api:access
Request body
handoffCodeRequest
Response
200: object of string
Errors
400: invalid_json; 415: content_type

POST /api/v1/account/step-up-handoff/lookup

Create a lookup

Permission
api:access
Request body
handoffCodeRequest
Response
200: HandoffView
Errors
400: invalid_json; 415: content_type

POST /api/v1/account/step-up-handoff/proofs

Create a proof

Permission
api:access
Request body
handoffProofRequest
Response
200: object of string
Errors
400: invalid_json; 415: content_type

POST /api/v1/account/step-up/{id}/email

Email a step up

Permission
api:access
Path parameters
id
Response
202: object of string

POST /api/v1/account/step-up/{id}/handoff

Handoff a step up

Permission
api:access
Path parameters
id
Response
201: object of any

POST /api/v1/account/step-up/{id}/handoff/token

Create a token

Permission
api:access
Path parameters
id
Response
200: object of any

POST /api/v1/account/step-up/{id}/proofs

Create a proof for a step up

Permission
api:access
Path parameters
id
Request body
elevationProofRequest
Response
200: object of any
Errors
400: invalid_json; 415: content_type

GET /api/v1/me/access-requests

The caller's own requests in their organization (never resource_access ones). Query: status (default all), limit (1-200), offset.

Permission
api:access
Query parameters
status
Errors
400: invalid_query, validation_error; 401: unauthorized; 503: requests_unavailable

POST /api/v1/me/access-requests

Create an access request

Permission
api:access
Request body
object
Response
201: AccessRequest
Errors
400: invalid_body, validation_error; 401: unauthorized

GET /api/v1/me/harness

Returns the signed pack chain that applies to the caller (GET /api/v1/me/harness). The service delivers only a chain whose every pack the caller may use (harness.packs:use): a more specific assignment with an unusable pack is passed over for the next one and listed in the response's skipped.

Permission
harness:read
Query parameters
engine, project, reason
Response
200: Resolution
Errors
400: reason_in_query, validation_error; 401: unauthorized; 403: forbidden; 404: not_found; 409: conflict, eval_gate; 503: authorization_unavailable, signing_unavailable

POST /api/v1/me/harness/events

Is the user-authenticated harness activity ingest route (POST /api/v1/me/harness/events), rate-limited per user.

Permission
harness:read
Query parameters
reason
Request body
object
Response
202: IngestResult
Errors
400: invalid_json, reason_in_query, validation_error; 401: unauthorized; 403: forbidden; 404: not_found; 409: conflict, eval_gate; 429: rate_limited; 503: authorization_unavailable, signing_unavailable

GET /api/v1/me/notification-settings

List notification settings

Permission
signed in
Errors
401: unauthorized; 403: person_required

PUT /api/v1/me/notification-settings

Set notification settings

Permission
signed in
Request body
object
Errors
400: invalid_request; 401: unauthorized; 403: person_required, role_session_read_only; 503: unavailable

GET /api/v1/me/notifications

List notifications

Permission
signed in
Query parameters
after, limit, unread
Response
200: Page
Errors
400: invalid_request; 401: unauthorized; 403: person_required

POST /api/v1/me/notifications/{id}/read

Read a notification

Permission
signed in
Path parameters
id
Errors
401: unauthorized; 403: person_required, role_session_read_only; 404: not_found

POST /api/v1/me/notifications/read-all

Create a read all

Permission
signed in
Response
200: object of any
Errors
401: unauthorized; 403: person_required, role_session_read_only

GET /api/v1/me/notifications/unread-count

List unread count

Permission
signed in
Response
200: object of any
Errors
401: unauthorized; 403: person_required

GET /api/v1/me/observe/metrics

The caller's own series of the built-in namespaces only, since anyone with observe:write could put a custom series naming someone else's UserId with their values per period and the statistic over the whole window, all computed here. Query parameters: Namespace, Stat (default Sum), Period in seconds (default 3600), StartTime and EndTime (RFC 3339, default the last 24 hours).

Permission
signed in
Query parameters
EndTime, Namespace, Period, StartTime, Stat
Response
200: MyMetricsOutput

GET /api/v1/me/permissions

List permissions

Permission
signed in
Query parameters
node
Response
200: Effective; 200: object of JSON
Errors
401: unauthorized; 403: permission_denied

GET /api/v1/me/policies

List policies

Permission
api:access
Response
200: object of any
Errors
401: unauthorized

GET /api/v1/me/sessions

List sessions

Permission
api:access
Response
200: object of any
Errors
400: invalid_query; 401: unauthorized

GET /api/v1/me/usage

List usage

Permission
api:access
Response
200: MyUsage
Errors
401: unauthorized

GET /api/v1/notifications/unsubscribe

List unsubscribe

Permission
none
Query parameters
token

POST /api/v1/notifications/unsubscribe

Create an unsubscribe

Permission
none
Query parameters
token
Errors
400: invalid_request, invalid_token

POST /api/v1/passkeys/register/begin

Create a begin

Permission
api:access
Request body
object
Response
200: RegistrationOptions
Errors
400: invalid_json; 401: unauthorized; 415: content_type; 503: step_up_unavailable

POST /api/v1/passkeys/register/complete

Create a complete

Permission
api:access
Request body
completeRegistrationRequest
Response
201: object of any
Errors
400: invalid_json, registration_failed, validation_error; 401: unauthorized; 415: content_type; 503: step_up_unavailable

GET /api/v1/privacy/dsar

One's own requests.

Permission
api:access
Query parameters
sla, status
Errors
400: invalid_query, resolution_required, validation_error; 403: person_required; 404: not_found; 409: already_extended, export_required, invalid_transition, no_export, request_closed; 410: link_invalid; 503: privacy_unavailable

POST /api/v1/privacy/dsar

A member files a request for themselves: the subject is always the signed-in person, with their account email.

Permission
api:access
Request body
object
Response
201: object of any
Errors
400: invalid_body, resolution_required, validation_error; 403: person_required; 404: not_found; 409: already_extended, export_required, invalid_transition, no_export, request_closed; 410: link_invalid; 503: audit_unavailable, privacy_unavailable

POST /api/v1/privacy/dsar-exports/download

The export behind a valid signed link, recorded as downloaded. The link is the credential: it names one export and expires after ten minutes.

Permission
none
Request body
object
Errors
400: invalid_body, resolution_required, validation_error; 404: not_found; 409: already_extended, export_required, invalid_transition, no_export, request_closed; 410: link_invalid; 429: rate_limited; 503: privacy_unavailable

GET /api/v1/privacy/dsar/{id}

One's own request.

Permission
api:access
Path parameters
id
Errors
400: resolution_required, validation_error; 403: person_required; 404: not_found; 409: already_extended, export_required, invalid_transition, no_export, request_closed; 410: link_invalid; 503: privacy_unavailable

POST /api/v1/privacy/dsar/{id}/exports/{exportID}/link

The subject's own export.

Permission
api:access
Path parameters
id, exportID
Errors
400: resolution_required, validation_error; 403: person_required; 404: not_found; 409: already_extended, export_required, invalid_transition, no_export, request_closed; 410: link_invalid; 503: privacy_unavailable

GET /api/v1/sessions/{id}/budget

Budget of a session

Permission
api:access
Path parameters
id
Response
200: SessionBudget
Errors
401: unauthorized; 404: not_found

POST /api/v1/sessions/{id}/budget

Budget a session

Permission
api:access
Path parameters
id
Request body
declareBudgetRequest
Response
201: SessionBudget
Errors
400: invalid_json, validation_error; 401: unauthorized; 403: budget.session_write_denied; 404: not_found; 409: budget_exists; 415: content_type; 422: budget_exceeds_caps

POST /api/v1/sessions/{id}/usage

Usage a session

Permission
api:access
Path parameters
id
Request body
recordUsageRequest
Errors
400: invalid_json, validation_error; 401: unauthorized; 403: budget.session_write_denied, not_session_owner; 404: not_found; 409: session_inactive; 415: content_type

POST /api/v1/svc/account/CloseAccount

Close account

Permission
account.lifecycle:closeaccount
Request body
accountIDIn
Response
200: object

POST /api/v1/svc/account/DeleteAlternateContact

Delete alternate contact

Permission
account.contacts:deletealternatecontact

POST /api/v1/svc/account/DisableRegion

Disable region

Permission
account.regions:disableregion

POST /api/v1/svc/account/EnableRegion

Enable region

Permission
account.regions:enableregion

POST /api/v1/svc/account/GetAccountInformation

Get account information

Permission
account.info:getaccountinformation

POST /api/v1/svc/account/GetAlternateContact

Get alternate contact

Permission
account.contacts:getalternatecontact

POST /api/v1/svc/account/GetContactInformation

Get contact information

Permission
account.contacts:getcontactinformation

POST /api/v1/svc/account/GetRegionOptStatus

Get region opt status

Permission
account.regions:getregionoptstatus

POST /api/v1/svc/account/ListRegions

List regions

Permission
account.regions:listregions

POST /api/v1/svc/account/PutAccountName

Put account name

Permission
account.info:putaccountname

POST /api/v1/svc/account/PutAlternateContact

Put alternate contact

Permission
account.contacts:putalternatecontact

POST /api/v1/svc/account/PutContactInformation

Put contact information

Permission
account.contacts:putcontactinformation

POST /api/v1/svc/account/PutIamBillingAccess

Put iam billing access

Permission
account.billingaccess:putiambillingaccess

POST /api/v1/svc/account/ReopenAccount

Reopen account

Permission
account.lifecycle:reopenaccount

POST /api/v1/svc/account/UpdateRootEmail

Update root email

Permission
account.root:updaterootemail

Objects

object

FieldTypeDescription
display_namestring

object

FieldTypeDescription
new_emailstring
current_passwordstring

object

FieldTypeDescription
current_passwordstring
new_passwordstring

object

FieldTypeDescription
request_typestring
target_resourcestring
business_reasonstring
session_idstring

object

FieldTypeDescription
eventsarray of ActivityEvent

object

FieldTypeDescription
emailstring
display_namestring

object

FieldTypeDescription
typestring
notesstring

object

FieldTypeDescription
tokenstring

object

FieldTypeDescription
getting_started_hidden optionalboolean
sidebar_collapsed optionalboolean

object

FieldTypeDescription
categorystring
in_app optionalboolean
email optionalboolean

object

No fields.

SessionBudget

SessionBudget represents the budget constraints and usage for an agent session.

FieldTypeDescription
idstring
agent_idstring
session_idstring
max_cost_usd optionalnumber
max_input_tokens optionalinteger
max_output_tokens optionalinteger
max_session_duration_minutes optionalinteger
max_idle_minutesinteger
max_turns optionalinteger
input_tokens_usedinteger
output_tokens_usedinteger
turns_usedinteger
started_attimestamp
last_activity_attimestamp
statusstring
created_attimestamp
owner_user_id optionalstringOwnerUserID and OwnerAPIKeyID name who declared the budget: only they, or an administrator, write it. Both are empty for a budget declared before owners were kept.
owner_api_key_id optionalstring

ConditionStep

The evaluation of one condition of an IAM policy statement, with the request's value for its key.

FieldTypeDescription
operatorstring
keystring
valuesarray of string
context optionalarray of string
missing optionalboolean
resultstring
error optionalstring

Dimension

A name and value pair that identifies a metric together with its namespace and name.

FieldTypeDescription
Namestring
Valuestring

Explanation

A decision with the chain of objects that produced it.

FieldTypeDescription
allowedboolean
decided_bystringDecidedBy names the step that decided.
revisionstringThe organization's access revision the decision was computed at.
step_up optionalStepUpRequirementSet when a deny policy asks for re-verification.
permissionstring
nodeNodeRef
resource optionalResourceRefSet for a check on one object; Node is then its owner node.
principalPrincipalRef
stepsarray of Step
action optionalstringThe permission's IAM action; ResourceNRN the NRN the check's IAM policy statements were matched against ("*" for an action without resource types).
resource_nrn optionalstring
missing_context_keys optionalarray of stringThe condition keys an evaluated IAM policy statement read that the request did not have.
mac optionalMACOutcomeHow mandatory access control decided (step 4.5).

MACLabel

A classification label as an explanation and the API show it.

FieldTypeDescription
classificationstring
compartmentsarray of string

MACOutcome

How MAC decided a check. It is always set by the engine; the labels are filled in explanations only.

FieldTypeDescription
evaluatedbooleanSet when the MAC step ran.
rule optionalstringRule names the rule that applied (MACRule*).
relaxed optionalbooleanSet for a write allowed only by the organization's own-level rule.
bypass optionalstringSet when a super admin passed MAC on platform metadata, with the reason.
resource optionalMACLabelThe effective label of the checked node; Clearances the principal's.
clearances optionalarray of MACLabel

MyMetric

One of the member's own series with its values over the requested window.

FieldTypeDescription
Namespacestring
MetricNamestring
Dimensionsarray of Dimension
Unitstring
Statstring
Timestampsarray of timestamp
Valuesarray of number
Total optionalnumberThe statistic over the whole window.

MyMetricsOutput

FieldTypeDescription
StartTimetimestamp
EndTimetimestamp
Periodinteger
Metricsarray of MyMetric

NodeRef

NodeRef identifies a node in explanations.

FieldTypeDescription
idstring
kindstring
pathstring

PrincipalRef

PrincipalRef identifies a principal in explanations and API payloads.

FieldTypeDescription
typestring
idstring

ResourceRef

ResourceRef identifies a shared object in explanations and API payloads.

FieldTypeDescription
typestring
idstring

Step

One entry in an explanation.

FieldTypeDescription
kindstring
id optionalstring
node_id optionalstring
inherited_from optionalstringSet when the step's object is on an ancestor of the checked node.
role optionalstring
via optionalPrincipalRef
resource optionalResourceRefSet on a step of a resource binding.
effectstring
reason optionalstring
policy_nrn optionalstringThe statement of an IAM policy step.
policy_type optionalstring
version_id optionalstring
sid optionalstring
statement optionalinteger
attached_to optionalPrincipalRef
conditions optionalarray of ConditionStep

StepUpRequirement

What a deny-with-step-up asks: a factor of at least Strength proved within MaxAgeSeconds.

FieldTypeDescription
strengthstring
max_age_secondsinteger

AccessRequest

A single row in self_service_access_requests.

FieldTypeDescription
idstring
org_idstring
requester_idstring
request_typestring
target_resourcestring
business_reasonstring
session_id optionalstring
statusstring
reviewed_by optionalstring
review_reason optionalstring
approved_until optionaltimestamp
created_attimestamp
reviewed_at optionaltimestamp
ide_device_id optionalstringIDE requests (filed by the device agent): the device, the app and action asked for, the minutes asked for, and when the pending request expires.
ide_app optionalstring
ide_action optionalstring
requested_minutes optionalinteger
expires_at optionaltimestamp
revoked_at optionaltimestamp
decidablebooleanDecidable: the request is pending and unexpired.

MyUsage

MyUsage holds self-service usage figures for the portal dashboard.

FieldTypeDescription
today_cost_usdnumber
month_cost_usdnumber
top_toolsarray of ToolBreakdown

ToolBreakdown

A (tool, cost) pair used in MyUsage.

FieldTypeDescription
toolstring
cost_usdnumber

ActivityEvent

One harness event from the IDE. It carries identifiers, counts and outcomes only; there is deliberately no field for code, prompts or completions.

FieldTypeDescription
event_idstring
typestring
occurred_attimestamp
packPackRef
experiment_id optionalstring
arm optionalstring
enginestring
modelstring
project optionalstring
outcome optionalstring
reworked optionalboolean
duration_ms optionalinteger
input_tokens optionalinteger
output_tokens optionalinteger
cost_usd optionalnumber

ChainEntry

One signed layer in a /me/harness response, starter first.

FieldTypeDescription
idstring
publisherstring
versionstring
kindstring
namestring
parent optionalParentRef
statusstring
published_atstring
manifestJSON
sha256string
signaturestring
pq_signature optionalstring
key_idstring

IngestResult

IngestResult reports how many events were stored and how many were already known.

FieldTypeDescription
acceptedinteger
duplicatesinteger

PackRef

PackRef identifies the pack version an event is about, as the IDE knows it from /me/harness.

FieldTypeDescription
idstring
publisherstring
versionstring

ParentRef

ParentRef names the layer a pack version builds on.

FieldTypeDescription
idstring
publisherstring
versionstring

Resolution

The /api/v1/me/harness response. Assignment is null when nothing is assigned and the platform starter for the requested engine is served.

FieldTypeDescription
assignment optionalResolvedAssignment
chainarray of ChainEntry
skipped optionalarray of SkippedAssignment
etagstring

ResolvedAssignment

ResolvedAssignment tells the IDE where its pack came from, and the experiment arm to tag metrics with.

FieldTypeDescription
scopestring
scope_idstring
experiment_id optionalstring
arm optionalstring

SkippedAssignment

An assignment (or an experiment's candidate arm, Arm set) that resolution passed over, and why.

FieldTypeDescription
scopestring
scope_idstring
arm optionalstring
reasonstring

Notification

One notification for one person in one organization.

FieldTypeDescription
iduuid
kindstringKind names what it is about, dotted ("approval.decided").
titlestring
body optionalstring
link optionalstringA console path under the account ("/approvals/<id>"), never an address.
created_attimestamp
read_at optionaltimestamp

Page

One page of a person's inbox, newest first.

FieldTypeDescription
notificationsarray of Notification
next optionalstringThe cursor of the following page; empty on the last page.

AuthenticationOptions

FieldTypeDescription
challengestring
timeoutinteger
rpIdstring
userVerificationstring
allowCredentials optionalarray of CredentialDescriptor

AuthenticatorSelection

FieldTypeDescription
authenticatorAttachment optionalstring
residentKeystring
userVerificationstring

CredentialDescriptor

FieldTypeDescription
typestring
idstring
transports optionalarray of string

PubKeyCredParam

FieldTypeDescription
typestring
alginteger

PublicKeyUser

FieldTypeDescription
idstring
namestring
displayNamestring

RegistrationOptions

FieldTypeDescription
challengestring
rpRelyingParty
userPublicKeyUser
pubKeyCredParamsarray of PubKeyCredParam
timeoutinteger
attestationstring
authenticatorSelectionAuthenticatorSelection
excludeCredentials optionalarray of CredentialDescriptor

RelyingParty

FieldTypeDescription
idstring
namestring

Effective

A principal's effective permissions on a node.

FieldTypeDescription
principalPrincipalRef
nodeNodeRef
revisionstring
permissionsarray of string
explanations optionalarray of ExplanationExplanations, when requested, cover every granted permission and every permission a binding would grant but a deny policy, ceiling, separation-of-duties rule or disabled state blocks.

Key

A stored public key.

FieldTypeDescription
iduuid
namestring
public_keystring
fingerprintstring
created_attimestamp

ElevationChallenge

A started or partly proved re-verification.

FieldTypeDescription
idstring
actionstring
methodsarray of string
factors_requiredinteger
methods_donearray of string
reasons optionalarray of string
expires_attimestamp
passkey optionalAuthenticationOptionsThe assertion request when a passkey is accepted.
email_sent optionalbooleanEmailSent says a code was emailed (the email code is accepted).

HandoffView

What the console page shows of a claimed hand-off.

FieldTypeDescription
actionstring
factors_requiredinteger
methods_donearray of string
requested_attimestamp
requested_from optionalstring
request_user_agent optionalstring
expires_attimestamp
passkey optionalAuthenticationOptionsA fresh assertion request for this person.

AcceptedInvitation

What accepting an invitation as an existing login did.

FieldTypeDescription
invitation_idstring
organization_idstring
membership_idstring
role_idstring

UserInvitation

A pending invitation addressed to a person, as the person sees it.

FieldTypeDescription
idstring
organization_idstring
organization_namestring
role_namestring
invited_by optionalstring
created_attimestamp
expires_attimestamp

ConsolePreferences

A person's console presentation choices in one account. They decide nothing about access: they only shape what the console shows that person.

FieldTypeDescription
getting_started_hiddenbooleanGettingStartedHidden: the person turned off "Show Get started when I sign in" (the console then lands a sign-in on Home instead of Get started). Presentation only.
sidebar_collapsed optionalbooleanSidebarCollapsed: the person collapsed the service sidebar to its rail (Cmd+B); absent until they first choose (db/migrations/006650_console_sidebar_preference.up.sql).
updated_at optionaltimestampWhen the person last changed them; absent while they are the defaults.

ResolvedAccount

FieldTypeDescription
account_idstringThe 12-digit Account ID, the form console URLs carry.
organization_idstringThe organization UUID, the ID every other API route takes.
namestring
aliasstringThe account alias (the organization slug).
matched_bystringWhat the reference was: account_id, alias or organization_id.
canonicalbooleanTrue when the reference is exactly the Account ID.
currentbooleanTrue when the caller's credentials are for this account; otherwise the caller is a member who has to sign in to it to act there.

accountIDIn

FieldTypeDescription
AccountIdstring

addSSHKeyBody

FieldTypeDescription
namestring
public_keystring

alertView

FieldTypeDescription
idstring
reasonsarray of string
ipstring
countrystring
user_agentstring
created_attimestamp
link_expires_attimestamp
confirmed_at optionaltimestamp
reported_at optionaltimestamp
statestring
browserstring
answersarray of stringThe answers the alert accepts from the calling session, decided here (signinguard.Answers): "confirm" only from a session that started before the alerted sign-in, "report" until the alert is reported.

completeRegistrationRequest

FieldTypeDescription
responseJSON
namestring
credential_idstringFields of the former unverified registration body, refused with an explanation.
public_keystring
aaguidstring
sign_countinteger
transportsarray of string
backed_upboolean

declareBudgetRequest

FieldTypeDescription
agent_idstring
max_cost_usd optionalnumber
max_input_tokens optionalinteger
max_output_tokens optionalinteger
max_session_duration_minutes optionalinteger
max_idle_minutes optionalinteger
max_turns optionalinteger

deviceHeartbeatRequest

FieldTypeDescription
machineIdstring
deviceNamestring
versionstring
osstring
lastActivestring
isActiveboolean

elevationBeginRequest

FieldTypeDescription
actionstring
request_hashstring

elevationProofRequest

FieldTypeDescription
methodstring
codestring
credential_idstring
client_data_jsonstring
authenticator_datastring
signaturestring
user_handlestring

handoffCodeRequest

FieldTypeDescription
user_codestring

handoffProofRequest

FieldTypeDescription
user_codestring
credential_idstring
client_data_jsonstring
authenticator_datastring
signaturestring
user_handlestring

personalKeyCreated

FieldTypeDescription
idstring
namestring
key_prefixstring
scopesarray of string
expires_at optionaltimestamp
last_used_at optionaltimestamp
revoked_at optionaltimestamp
created_attimestamp
statestringActive, expired or revoked, decided by the server.
keystring
rotated_from optionalstringRotatedFrom and PreviousExpiresAt describe the key a rotation replaced.
previous_expires_at optionaltimestamp

personalKeyRequest

FieldTypeDescription
namestring
scopesarray of string
expires_at optionaltimestamp

personalRotateRequest

FieldTypeDescription
overlap_seconds optionalinteger

recordUsageRequest

FieldTypeDescription
input_tokensinteger
output_tokensinteger
cost_usdnumber

This page is generated from the server's route table and the Go handlers that serve each route. Do not edit it by hand.