Account API

The account API allows users to query and manipulate their own account data.

Create a new account. The response is the created account data.

Path	Method	Protected
`/v1/accounts`	POST	Yes

Example Request JSON


{
  "name": "string",
  "email": "string",
  "roles": [
    "admin"
  ]
}

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "revision": 0,
  "name": "string",
  "email": "string",
  "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",
  "roles": [
    "admin"
  ],
  "accountRootCardId": "dc9e74a3-7f70-412c-9cf0-c0704225960b"
}

Retrieve an account for a given Account ID

Path	Method	Protected
`/v1/accounts/{account_id}`	GET	Yes

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "revision": 0,
  "name": "string",
  "email": "string",
  "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",
  "roles": [
    "admin"
  ],
  "accountRootCardId": "dc9e74a3-7f70-412c-9cf0-c0704225960b"
}

Delete an account.

Path	Method	Protected
`/v1/accounts/{account_id}`	DELETE	Yes

Query Parameters

Name	Type	Required	Description
current_revision	integer	Yes	-

Example Response JSON

{}

Update account

Path	Method	Protected
`/v1/accounts/{account_id}`	PATCH	Yes

Allows the user to change mutable account details such as name.

The account email is immutable after account creation.

Changing the planId is not allowed and the request will be rejected. The response is the updated account data.

Example Request JSON


{
  "currentRevision": 0,
  "name": "string"
}

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "revision": 0,
  "name": "string",
  "email": "string",
  "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",
  "roles": [
    "admin"
  ],
  "accountRootCardId": "dc9e74a3-7f70-412c-9cf0-c0704225960b"
}

Retrieve an account by email address.

Path	Method	Protected
`/v1/accounts/by-email/{account_email}`	GET	Yes

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "revision": 0,
  "name": "string",
  "email": "string",
  "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",
  "roles": [
    "admin"
  ],
  "accountRootCardId": "dc9e74a3-7f70-412c-9cf0-c0704225960b"
}

Get an account’s plan

Path	Method	Protected
`/v1/accounts/{account_id}/plan`	GET	Yes

Example Response JSON


{
  "appLimit": 10,
  "blobStorageLimit": 18446744073709552000,
  "componentLimit": 100,
  "envLimit": 40,
  "maxConcurrentAgentsPerExecutor": 100,
  "maxMemoryPerAgent": {
    "type": "unlimited"
  },
  "maxMemoryPerAgentCeiling": {
    "type": "unlimited"
  },
  "maxMemoryPerAgentUserConfigurable": false,
  "maxStoragePerAgent": {
    "reason": "managedFilesystemUnavailable",
    "type": "disabled"
  },
  "maxStoragePerAgentCeiling": {
    "reason": "managedFilesystemUnavailable",
    "type": "disabled"
  },
  "maxStoragePerAgentUserConfigurable": false,
  "maxTableElementsPerWorker": 16384,
  "monthlyComputeGcu": 100,
  "monthlyDurableStorageGbMonth": 50,
  "monthlyEphemeralStorageGbMonth": 25,
  "monthlyHttpCallLimit": 10000,
  "monthlyMemoryGbSeconds": 10000,
  "monthlyRpcCallLimit": 10000,
  "monthlyUploadLimit": 1000000000,
  "name": "default",
  "oplogWritesPerSecond": 1000,
  "overageAllowedByPlan": false,
  "perInvocationHttpCallLimit": 1000,
  "perInvocationRpcCallLimit": 1000,
  "planId": "00000000-0000-0000-0000-000000000001",
  "storageLimit": 500000000,
  "workerConnectionLimit": 100
}

Set the plan of an account

Path	Method	Protected
`/v1/accounts/{account_id}/plan`	PUT	Yes

Example Request JSON


{
  "currentRevision": 0,
  "plan": "c685f150-7cb7-436f-9700-386be171480b"
}

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "revision": 0,
  "name": "string",
  "email": "string",
  "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",
  "roles": [
    "admin"
  ],
  "accountRootCardId": "dc9e74a3-7f70-412c-9cf0-c0704225960b"
}

List all tokens of an account.

The format of each element is the same as the data object in the oauth2 endpoint’s response.

Path	Method	Protected
`/v1/accounts/{account_id}/tokens`	GET	Yes

Example Response JSON


{
  "values": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
      "createdAt": "2019-08-24T14:15:22Z",
      "expiresAt": "2019-08-24T14:15:22Z"
    }
  ]
}

Create new token

Path	Method	Protected
`/v1/accounts/{account_id}/tokens`	POST	Yes

Creates a new token with a given expiration date. The response not only contains the token data but also the secret which can be passed as a bearer token to the Authorization header to the Golem Cloud REST API.

Example Request JSON


{
  "expiresAt": "2019-08-24T14:15:22Z"
}

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "secret": "stringstringstri",
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "createdAt": "2019-08-24T14:15:22Z",
  "expiresAt": "2019-08-24T14:15:22Z"
}

Get account usage for a UTC calendar month.

Path	Method	Protected
`/v1/accounts/{account_id}/usage`	GET	Yes

Compute is reported in GCU, memory in allocated linear-memory GB-seconds, and durable and ephemeral storage in GB-month using byte-seconds / (1024^3 * 730 * 3600). asOf is when the registry last received a usage snapshot for the period, or the response time if no snapshot exists. Metering status distinguishes enabled meters that measured zero from disabled meters. unknown means no usage producer has reported metering state for the period. Durable and ephemeral storage both use storage metering.

Query Parameters

Name	Type	Required	Description
period	string	No	Billing period in YYYY-MM format. Defaults to the current UTC calendar month.

Example Response JSON


{
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "usage": {
    "period": {
      "year": 0,
      "month": 1
    },
    "asOf": "2019-08-24T14:15:22Z",
    "computeGcu": 0.1,
    "memoryGbSeconds": 0,
    "durableStorageGbMonth": 0.1,
    "ephemeralStorageGbMonth": 0.1,
    "metering": {
      "compute": "enabled",
      "memory": "enabled",
      "durableStorage": "enabled",
      "ephemeralStorage": "enabled"
    }
  }
}

Get sparse account usage for closed UTC calendar months, newest first.

Path	Method	Protected
`/v1/accounts/{account_id}/usage/history`	GET	Yes

Each item uses the same metrics and metering-status contract as current usage. The response does not include plan or limit metadata because historical limits are not snapshotted.

Query Parameters

Name	Type	Required	Description
last	integer	No	-

Example Response JSON


[
  {
    "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
    "usage": {
      "period": {
        "year": 0,
        "month": 1
      },
      "asOf": "2019-08-24T14:15:22Z",
      "computeGcu": 0.1,
      "memoryGbSeconds": 0,
      "durableStorageGbMonth": 0.1,
      "ephemeralStorageGbMonth": 0.1,
      "metering": {
        "compute": "enabled",
        "memory": "enabled",
        "durableStorage": "enabled",
        "ephemeralStorage": "enabled"
      }
    }
  }
]

Get the current account resource policy.

Path	Method	Protected
`/v1/accounts/{account_id}/limits`	GET	Yes

The policy combines Plan Row monthly amounts with current UTC-period usage and both per-agent safety limits. Enabled monthly dimensions report measured usage and remaining capacity. Disabled dimensions omit the monthly amount, usage, remaining capacity, and behavior. unknown means no producer has reported metering state; it does not mean disabled or measured zero. Compute uses GCU, allocated linear memory uses GB-seconds, storage uses GB-month, and per-agent limits use bytes. Monthly behavior is hardLimit or includedAllowance, according to the account’s current usage mode.

Example Response JSON


{
  "accountId": "00000000-0000-0000-0000-000000000001",
  "maxMemoryPerAgent": {
    "ceiling": {
      "type": "unlimited"
    },
    "effectiveValue": {
      "type": "unlimited"
    },
    "planDefault": {
      "type": "unlimited"
    },
    "unit": "bytes",
    "userConfigurable": false
  },
  "maxStoragePerAgent": {
    "ceiling": {
      "type": "finite",
      "value": 10737418240
    },
    "effectiveValue": {
      "reason": "managedFilesystemUnavailable",
      "type": "disabled"
    },
    "planDefault": {
      "type": "finite",
      "value": 1073741824
    },
    "unit": "bytes",
    "userConfigurable": false
  },
  "monthly": {
    "computeGcu": {
      "allowOverageUsage": 0,
      "behavior": "hardLimit",
      "metering": "enabled",
      "planAmount": 100,
      "remaining": 75,
      "resolvedMonthlyAmount": 100,
      "unit": "GCU",
      "usage": 25
    },
    "durableStorageGbMonth": {
      "allowOverageUsage": 0,
      "behavior": "hardLimit",
      "metering": "enabled",
      "planAmount": 50,
      "remaining": 37.5,
      "resolvedMonthlyAmount": 50,
      "unit": "GB-month",
      "usage": 12.5
    },
    "ephemeralStorageGbMonth": {
      "allowOverageUsage": 0,
      "behavior": "hardLimit",
      "metering": "enabled",
      "planAmount": 25,
      "remaining": 20,
      "resolvedMonthlyAmount": 25,
      "unit": "GB-month",
      "usage": 5
    },
    "memoryGbSeconds": {
      "allowOverageUsage": 0,
      "behavior": "hardLimit",
      "metering": "enabled",
      "planAmount": 10000,
      "remaining": 7500,
      "resolvedMonthlyAmount": 10000,
      "unit": "GB-seconds",
      "usage": 2500
    }
  },
  "monthlyUsageMode": "hardLimit",
  "overageAllowedByPlan": false
}

Explicitly enter or leave paid-overage mode.

Path	Method	Protected
`/v1/accounts/{account_id}/monthly-usage-mode`	PUT	Yes

Only the account owner can enable overage, and the current Plan Row must permit it. Administrators impersonating the account may force hardLimit, but cannot enable overage. Each successful transition records immutable consent history. Requests that repeat the current mode are rejected and do not add history.

Example Request JSON


{
  "mode": "hardLimit"
}

Example Response JSON


{
  "actorAccountId": "00000000-0000-0000-0000-000000000001",
  "changedAt": "2023-11-14T22:13:20+00:00",
  "newMode": "hardLimit",
  "previousMode": "allowOverage",
  "source": "owner"
}

Set a storage-per-agent override for the authenticated account owner.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/max-storage-per-agent`	PUT	Yes

Example Request JSON


{
  "value": 0
}

Example Response JSON


{
  "activeAdminGrant": {
    "actorAccountId": "00000000-0000-0000-0000-000000000002",
    "dimension": "maxStoragePerAgent",
    "grantedAt": "2023-11-14T22:13:20+00:00",
    "reason": "support",
    "value": 2147483648
  },
  "ceiling": {
    "type": "finite",
    "value": 10737418240
  },
  "effectiveValue": {
    "type": "finite",
    "value": 2147483648
  },
  "planDefault": {
    "type": "finite",
    "value": 1073741824
  },
  "unit": "bytes",
  "userConfigurable": true
}

Clear a storage-per-agent override for an account.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/max-storage-per-agent`	DELETE	Yes

Example Response JSON


{
  "activeAdminGrant": {
    "actorAccountId": "00000000-0000-0000-0000-000000000002",
    "dimension": "maxStoragePerAgent",
    "grantedAt": "2023-11-14T22:13:20+00:00",
    "reason": "support",
    "value": 2147483648
  },
  "ceiling": {
    "type": "finite",
    "value": 10737418240
  },
  "effectiveValue": {
    "type": "finite",
    "value": 2147483648
  },
  "planDefault": {
    "type": "finite",
    "value": 1073741824
  },
  "unit": "bytes",
  "userConfigurable": true
}

Set the maximum linear memory per agent for the authenticated account owner.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/max-memory-per-agent`	PUT	Yes

Example Request JSON


{
  "value": 0
}

Example Response JSON


{
  "activeAdminGrant": {
    "actorAccountId": "00000000-0000-0000-0000-000000000002",
    "dimension": "maxMemoryPerAgent",
    "grantedAt": "2023-11-14T22:13:20+00:00",
    "reason": "support",
    "value": 2147483648
  },
  "ceiling": {
    "type": "finite",
    "value": 10737418240
  },
  "effectiveValue": {
    "type": "finite",
    "value": 2147483648
  },
  "planDefault": {
    "type": "finite",
    "value": 1073741824
  },
  "unit": "bytes",
  "userConfigurable": true
}

Clear the maximum linear memory per-agent override.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-overrides/max-memory-per-agent`	DELETE	Yes

Example Response JSON


{
  "activeAdminGrant": {
    "actorAccountId": "00000000-0000-0000-0000-000000000002",
    "dimension": "maxMemoryPerAgent",
    "grantedAt": "2023-11-14T22:13:20+00:00",
    "reason": "support",
    "value": 2147483648
  },
  "ceiling": {
    "type": "finite",
    "value": 10737418240
  },
  "effectiveValue": {
    "type": "finite",
    "value": 2147483648
  },
  "planDefault": {
    "type": "finite",
    "value": 1073741824
  },
  "unit": "bytes",
  "userConfigurable": true
}

Grant an account additional resources.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-grants/{dimension}`	PUT	Yes

This operation requires an administrator token. Promotional grants require a future expiry. Grants do not change the account’s paid-overage consent.

Example Request JSON


{
  "reason": "support",
  "value": 10
}

Example Response JSON


{
  "accountId": "00000000-0000-0000-0000-000000000001",
  "actorAccountId": "00000000-0000-0000-0000-000000000002",
  "changedAt": "2023-11-14T22:13:20+00:00",
  "dimension": "monthlyComputeGcu",
  "eventType": "override_granted",
  "newValue": {
    "type": "finite",
    "value": 10
  },
  "oldValue": 5,
  "reason": "support"
}

Clear an active admin resource grant.

Path	Method	Protected
`/v1/accounts/{account_id}/resource-grants/{dimension}`	DELETE	Yes

Example Response JSON


{
  "accountId": "00000000-0000-0000-0000-000000000001",
  "actorAccountId": "00000000-0000-0000-0000-000000000002",
  "changedAt": "2023-11-14T22:13:20+00:00",
  "dimension": "monthlyComputeGcu",
  "eventType": "override_cleared",
  "newValue": {
    "type": "finite",
    "value": 5
  },
  "oldValue": 10,
  "reason": "support"
}

Create an impersonation token for a target account

Path	Method	Protected
`/v1/admin/impersonate/{account_id}`	POST	Yes

Creates a short-lived token that, when used for authentication, produces an AdminImpersonation auth context: access and visibility checks run as the target account, but audit writes (created_by fields) record the admin’s account ID.

Only users with the Admin account role may call this endpoint.

Example Request JSON


{
  "expiresAt": "2019-08-24T14:15:22Z"
}

Example Response JSON


{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "secret": "stringstringstri",
  "accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
  "createdAt": "2019-08-24T14:15:22Z",
  "expiresAt": "2019-08-24T14:15:22Z"
}

Account API Errors

Status Code	Description	Body
400	Invalid request, returning with a list of issues detected in the request	`{"code":"string","errors":["string"]}`
401	Unauthorized request	`{"code":"string","error":"string"}`
403	Forbidden Request	`{"code":"string","error":"string"}`
404	Entity not found	`{"code":"string","error":"string"}`
409		`{"code":"string","error":"string"}`
422	Limits of the plan exceeded	`{"code":"string","error":"string"}`
500	Internal server error	`{"code":"string","error":"string"}`