{ "openapi": "3.0.3", "info": { "title": "Organization Management", "version": "2.0", "description": "Your project description" }, "paths": { "/v3/manage/auth-keys/": { "get": { "operationId": "manage_auth_keys_list", "description": "Lists the organization's management keys, newest first, including revoked ones. Secrets are never returned. Requires the `manage:mint` scope.", "summary": "List management keys", "tags": [ "Management Keys" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementKeyRead" } } } }, "description": "" } } }, "post": { "operationId": "manage_auth_keys_create", "description": "Creates a management key with the `manage:read` and/or `manage:write` scopes, so an automated system can manage the organization without a person in the loop. The `manage:mint` scope cannot be granted here; keys with that scope are created from the dashboard. The response includes the key's `secret` exactly once. Returns 409 if the name is already used by an active management key and 403 if the organization's management-key limit is reached. Requires the `manage:mint` scope.", "summary": "Create a management key", "tags": [ "Management Keys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementKeyMintRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ManagementKeyMintRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ManagementKeyMintRequest" } } }, "required": true }, "security": [ { "ManagementKeyAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedManagementKey" } } }, "description": "" } } } }, "/v3/manage/auth-keys/{key_id}/": { "delete": { "operationId": "manage_auth_keys_destroy", "description": "Permanently revokes a `manage:read`/`manage:write` management key of the organization. Keys with the `manage:mint` scope cannot be revoked here and return 403; revoke them from the dashboard. Revoking an already revoked key is a no-op. Returns the revoked key. Requires the `manage:mint` scope.", "summary": "Revoke a management key", "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Management Keys" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementKeyRead" } } }, "description": "" } } } }, "/v3/manage/groups/": { "get": { "operationId": "manage_groups_list", "description": "Lists the organization's groups synced from its identity provider (via directory sync), ordered by name, with the emails of their active members. Groups are managed in the identity provider and are read-only here. Requires the `manage:read` scope.", "summary": "List groups", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "Groups" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedManageGroupList" } } }, "description": "" } } } }, "/v3/manage/groups/{external_group_id}/": { "get": { "operationId": "manage_groups_retrieve", "description": "Returns one group of the organization by its identity-provider id, with the emails of its active members. A group that belongs to another organization returns 404. Requires the `manage:read` scope.", "summary": "Retrieve a group", "parameters": [ { "in": "path", "name": "external_group_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Groups" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageGroup" } } }, "description": "" } } } }, "/v3/manage/keys/": { "get": { "operationId": "manage_keys_list", "description": "Lists every API key of the organization, including revoked ones (marked with `revoked: true`). Secrets are never returned; use `masked` to identify a key. Requires the `manage:read` scope.", "summary": "List API keys", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "API Keys" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedManagementKeyList" } } }, "description": "" } } }, "post": { "operationId": "manage_keys_create", "description": "Creates a new API key for the organization, optionally attributed to a member and with spending controls. The response includes the key's `secret` exactly once; it cannot be retrieved afterwards. Returns 409 if the name is already used by one of the owner's active keys and 403 if the plan's key limit is reached. Requires the `manage:write` scope.", "summary": "Create an API key", "tags": [ "API Keys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementKeyCreateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ManagementKeyCreateRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ManagementKeyCreateRequest" } } }, "required": true }, "security": [ { "ManagementKeyAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintedManagementKey" } } }, "description": "" } } } }, "/v3/manage/keys/{key_id}/": { "get": { "operationId": "manage_keys_retrieve", "description": "Returns one API key of the organization by its `key_id`. A key that belongs to another organization returns 404. Requires the `manage:read` scope.", "summary": "Retrieve an API key", "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "API Keys" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementKey" } } }, "description": "" } } }, "patch": { "operationId": "manage_keys_partial_update", "description": "Updates the display name and spending controls of an API key. Only the fields you send are changed. The environment (`token_type`) cannot be changed. Returns 409 if the new name is already used by one of the owner's active keys. Requires the `manage:write` scope.", "summary": "Update an API key", "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "API Keys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedManagementKeyUpdateRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedManagementKeyUpdateRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedManagementKeyUpdateRequest" } } } }, "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementKey" } } }, "description": "" } } }, "delete": { "operationId": "manage_keys_destroy", "description": "Revokes an API key. This is permanent: the key stops authenticating immediately and cannot be re-enabled, but it stays listed with `revoked: true` for your records. Revoking an already revoked key is a no-op. Returns the revoked key. Requires the `manage:write` scope.", "summary": "Revoke an API key", "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "API Keys" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementKey" } } }, "description": "" } } } }, "/v3/manage/keys/{key_id}/rotate/": { "post": { "operationId": "manage_keys_rotate_create", "description": "Replaces the secret of an API key while keeping its identity, name, budget and settings. The previous secret stops working immediately and the new one is returned exactly once in this response. A revoked key cannot be rotated and returns 404. Requires the `manage:write` scope.", "summary": "Rotate an API key", "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "API Keys" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotatedApiKey" } } }, "description": "" } } } }, "/v3/manage/keys/{key_id}/usage/": { "get": { "operationId": "manage_keys_usage_retrieve", "description": "Returns the consumption of one API key over a date window, as a time series at the requested granularity, optionally narrowed by feature, subfeature, provider or phase. A key that belongs to another organization returns 404. Without `begin`/`end` the last 7 days are returned. Requires the `manage:read` scope.", "summary": "Get an API key's usage", "parameters": [ { "in": "query", "name": "begin", "schema": { "type": "string", "format": "date" }, "description": "First day of the window (inclusive). Provide both `begin` and `end`, or neither to get the last 7 days. Usage before 2026-09-03 is not available here; contact support." }, { "in": "query", "name": "end", "schema": { "type": "string", "format": "date" }, "description": "Day after the last day of the window (exclusive). The window may not exceed 366 days." }, { "in": "query", "name": "feature", "schema": { "type": "string", "minLength": 1 }, "description": "Only count this feature." }, { "in": "path", "name": "key_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "query", "name": "phase", "schema": { "type": "string", "minLength": 1 }, "description": "Only count this phase." }, { "in": "query", "name": "provider", "schema": { "type": "string", "minLength": 1 }, "description": "Only count this provider." }, { "in": "query", "name": "step", "schema": { "type": "integer", "maximum": 4, "minimum": 1 }, "description": "Granularity of the time series: 1 = day, 2 = week, 3 = month, 4 = year.", "required": true }, { "in": "query", "name": "subfeature", "schema": { "type": "string", "minLength": 1 }, "description": "Only count this subfeature." } ], "tags": [ "Usage" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyUsageResponse" } } }, "description": "" } } } }, "/v3/manage/members/": { "get": { "operationId": "manage_members_list", "description": "Lists the organization's active members, including the owner, ordered by email. Each member includes their role, rate limits, directory groups and active API keys; revoked keys are listed by `GET /v3/manage/keys` only. Requires the `manage:read` scope.", "summary": "List members", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } } ], "tags": [ "Members" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOrganisationUsersList" } } }, "description": "" } } } }, "/v3/manage/members/{email}/role/": { "patch": { "operationId": "manage_members_role_partial_update", "description": "Assigns a role to a member of the organization, identified by email, and returns the updated member. Role-based access control must be enabled for the organization (otherwise 409). The organization owner's role cannot be changed (403), and a management key can only assign roles limited to member management: roles granting organization or billing administration are refused (403). Requires the `manage:write` scope.", "summary": "Set a member's role", "parameters": [ { "in": "path", "name": "email", "schema": { "type": "string" }, "required": true } ], "tags": [ "Members" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedManageMemberRoleRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedManageMemberRoleRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedManageMemberRoleRequest" } } } }, "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationUsers" } } }, "description": "" } } } }, "/v3/manage/routing-policies/": { "get": { "operationId": "manage_routing_policies_list", "description": "Lists the routing policies you may use, ordered by name. A policy names the models to try for a request and how to pick among them, and is called from an inference request as `policy/{name}` or bound to an API key as its `default_policy`. Each entry's `scope` says whose it is. With a management key, the organization's policies are managed (`manage:read` to read, `manage:write` to write). With your own API key or session token, your personal policies are managed, and the organization's can be read.", "summary": "List routing policies", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "The initial index from which to return the results.", "schema": { "type": "integer" } }, { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "organization", "user" ] }, "description": "Only policies of this scope: `user` for your personal ones, `organization` for the organization's. Without it, both. A management key only ever sees the organization's." } ], "tags": [ "Routing Policies" ], "security": [ { "ManagementKeyOrUserAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedRoutingPolicyList" } } }, "description": "" } } } }, "/v3/manage/routing-policies/{name}/": { "get": { "operationId": "manage_routing_policies_retrieve", "description": "Returns one routing policy: your personal one of that name if you have one, else the organization's (`scope=organization` reads the organization's even when a personal one shadows it). The `ETag` header carries its version, to send back as `If-Match` on a conditional replace. With a management key, the organization's policies are managed (`manage:read` to read, `manage:write` to write). With your own API key or session token, your personal policies are managed, and the organization's can be read.", "summary": "Get a routing policy", "parameters": [ { "in": "path", "name": "name", "schema": { "type": "string" }, "description": "The policy's handle, as called with `policy/{name}`.", "required": true }, { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "organization", "user" ] }, "description": "Only policies of this scope: `user` for your personal ones, `organization` for the organization's. Without it, both. A management key only ever sees the organization's." } ], "tags": [ "Routing Policies" ], "security": [ { "ManagementKeyOrUserAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPolicy" } } }, "description": "" } } }, "put": { "operationId": "manage_routing_policies_update", "description": "Creates the policy (201) or replaces it whole (200), incrementing `version`, in the scope of your credential: the organization's with a management key, your personal one otherwise (a personal policy may share a name with the organization's and then wins on your keys). Send `If-Match: \"\"` to replace only the version you read; a mismatch is a 412 carrying the current version (0 when nothing is stored, and `If-Match: \"0\"` creates only when nothing is stored yet). A body that breaks a rule is a 422 whose `error.fields` names each offending field by path. Targets must be models the catalogue serves, canonical names, or aliases. With a management key, the organization's policies are managed (`manage:read` to read, `manage:write` to write). With your own API key or session token, your personal policies are managed, and the organization's can be read.", "summary": "Create or replace a routing policy", "parameters": [ { "in": "path", "name": "name", "schema": { "type": "string" }, "description": "The policy's handle, as called with `policy/{name}`.", "required": true }, { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "organization", "user" ] }, "description": "Optional, and only ever the scope your credential writes: `organization` with a management key, `user` with your own API key or session token. Naming the other one is refused (403) rather than silently written elsewhere." } ], "tags": [ "Routing Policies" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPolicyBodyRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RoutingPolicyBodyRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RoutingPolicyBodyRequest" } } } }, "security": [ { "ManagementKeyOrUserAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPolicy" } } }, "description": "" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPolicy" } } }, "description": "" } } }, "delete": { "operationId": "manage_routing_policies_destroy", "description": "Deletes the policy in the scope of your credential (the organization's with a management key, your personal one otherwise). API keys that used it as their `default_policy` lose the binding; requests naming it as `policy/{name}` are refused from then on, or fall through to the organization's policy of that name when a personal one shadowed it. With a management key, the organization's policies are managed (`manage:read` to read, `manage:write` to write). With your own API key or session token, your personal policies are managed, and the organization's can be read.", "summary": "Delete a routing policy", "parameters": [ { "in": "path", "name": "name", "schema": { "type": "string" }, "description": "The policy's handle, as called with `policy/{name}`.", "required": true }, { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "organization", "user" ] }, "description": "Optional, and only ever the scope your credential writes: `organization` with a management key, `user` with your own API key or session token. Naming the other one is refused (403) rather than silently written elsewhere." } ], "tags": [ "Routing Policies" ], "security": [ { "ManagementKeyOrUserAuth": [] } ], "responses": { "204": { "description": "No response body" } } } }, "/v3/manage/usage/": { "get": { "operationId": "manage_usage_retrieve", "description": "Returns the organization's aggregated consumption over a date window, as a time series per API key at the requested granularity. Narrow it by feature, provider, member or API key, or get one total per member with `group_by=user`. Without `begin`/`end` the last 7 days are returned. Requires the `manage:read` scope.", "summary": "Get organization usage", "parameters": [ { "in": "query", "name": "begin", "schema": { "type": "string", "format": "date" }, "description": "First day of the window (inclusive). Provide both `begin` and `end`, or neither to get the last 7 days. Usage before 2026-09-03 is not available here; contact support." }, { "in": "query", "name": "end", "schema": { "type": "string", "format": "date" }, "description": "Day after the last day of the window (exclusive). The window may not exceed 366 days." }, { "in": "query", "name": "feature", "schema": { "type": "string", "minLength": 1 }, "description": "Only count this feature." }, { "in": "query", "name": "group_by", "schema": { "enum": [ "user" ], "type": "string", "minLength": 1 }, "description": "Break the totals down per member.\n\n* `user` - user" }, { "in": "query", "name": "key_id", "schema": { "type": "string", "format": "uuid" }, "description": "Only count usage of this API key (404 if not in the organization)." }, { "in": "query", "name": "phase", "schema": { "type": "string", "minLength": 1 }, "description": "Only count this phase." }, { "in": "query", "name": "provider", "schema": { "type": "string", "minLength": 1 }, "description": "Only count this provider." }, { "in": "query", "name": "step", "schema": { "type": "integer", "maximum": 4, "minimum": 1 }, "description": "Granularity of the time series: 1 = day, 2 = week, 3 = month, 4 = year.", "required": true }, { "in": "query", "name": "subfeature", "schema": { "type": "string", "minLength": 1 }, "description": "Only count this subfeature." }, { "in": "query", "name": "token", "schema": { "type": "string", "minLength": 1 }, "description": "Only count usage of the API keys with this name. Use `base_token` for usage not attributed to any key. Ignored when `key_id` is given." }, { "in": "query", "name": "user", "schema": { "type": "string", "format": "email", "minLength": 1 }, "description": "Only count usage of this member (404 if not in the organization)." } ], "tags": [ "Usage" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageUsageResponse" } } }, "description": "" } } } }, "/v3/manage/whoami/": { "get": { "operationId": "manage_whoami_retrieve", "description": "Returns the organization, scopes and expiry of the management key used to authenticate the request. Any valid management key can call this endpoint, which makes it a convenient connectivity check. The key's secret is never returned.", "summary": "Inspect the calling management key", "tags": [ "Management Keys" ], "security": [ { "ManagementKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementKeyIdentity" } } }, "description": "" } } } } }, "components": { "schemas": { "BalanceResetPeriodEnum": { "enum": [ "none", "daily", "weekly", "monthly" ], "type": "string", "description": "* `none` - None\n* `daily` - Daily\n* `weekly` - Weekly\n* `monthly` - Monthly" }, "CredentialsEnum": { "enum": [ "auto", "own", "eden" ], "type": "string", "description": "* `auto` - auto\n* `own` - own\n* `eden` - eden" }, "Details": { "properties": { "total_cost": { "title": "Total Cost", "type": "number" }, "details": { "title": "Details", "type": "integer" }, "cost_per_provider": { "additionalProperties": { "type": "number" }, "title": "Cost Per Provider", "type": "object" } }, "required": [ "total_cost", "details", "cost_per_provider" ], "title": "Details", "type": "object" }, "IssuedManagementKey": { "type": "object", "description": "A freshly created management key. `secret` is the full key value, shown only in this\nresponse; store it securely.", "properties": { "key_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopesEnum" } }, "secret": { "type": "string" }, "masked": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "expires_at", "key_id", "masked", "name", "scopes", "secret" ] }, "KeyUsageResponse": { "description": "Usage of one API key as a time series.", "properties": { "usage": { "items": { "$ref": "#/components/schemas/TokenData" }, "title": "Usage", "type": "array" } }, "required": [ "usage" ], "title": "KeyUsageResponse", "type": "object" }, "LockEnum": { "enum": [ "sort", "sticky", "allow_fallbacks", "allowed_providers", "ignored_providers", "order", "max_price", "zero_data_retention", "region" ], "type": "string", "description": "* `sort` - sort\n* `sticky` - sticky\n* `allow_fallbacks` - allow_fallbacks\n* `allowed_providers` - allowed_providers\n* `ignored_providers` - ignored_providers\n* `order` - order\n* `max_price` - max_price\n* `zero_data_retention` - zero_data_retention\n* `region` - region" }, "ManageGroup": { "type": "object", "description": "A group synced from your identity provider. `external_group_id` is the group's id in the\nidentity provider and the identifier used in `/manage/groups/{external_group_id}` URLs;\n`members` lists the emails of the group's active members.", "properties": { "external_group_id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "members": { "type": "array", "items": { "type": "string", "format": "email" }, "readOnly": true } }, "required": [ "external_group_id", "members", "name" ] }, "ManageUsageResponse": { "description": "Organization usage: a time series per API key, or one total per member when\n`group_by=user` is set.", "properties": { "usage": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TokenData" }, "type": "array" }, { "items": { "$ref": "#/components/schemas/UserCostTotal" }, "type": "array" } ], "title": "Usage" } }, "required": [ "usage" ], "title": "ManageUsageResponse", "type": "object" }, "ManagementKey": { "type": "object", "description": "An API key belonging to the organization. The secret is never included: `masked` shows the\nkey prefix and last characters for identification, and `id` is the stable identifier used in\n`/manage/keys/{key_id}` URLs.\n\n`balance` is the remaining spendable amount, including usage not yet settled, or null when the\nkey has no spending cap. Revoked keys stay listed with `revoked: true` and a `revoked_at`\ntimestamp. `id` is null for a legacy key that has not been regenerated yet; such a key is\nlisted but cannot be addressed by URL until it is regenerated.", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true }, "name": { "type": "string", "description": "The token name", "maxLength": 200 }, "token_type": { "$ref": "#/components/schemas/TokenTypeD53Enum" }, "member": { "type": "string", "format": "email", "readOnly": true }, "masked": { "type": "string", "readOnly": true }, "active_balance": { "type": "boolean", "description": "Weither to use the balance field or not." }, "balance": { "type": "number", "format": "double", "maximum": 100000, "minimum": -100000, "exclusiveMaximum": true, "exclusiveMinimum": true, "nullable": true, "readOnly": true }, "expire_time": { "type": "string", "format": "date-time", "nullable": true }, "default_tags": { "nullable": true, "description": "Tags added to every call made with this key. A tag the call sends itself wins on the same key." }, "default_policy": { "type": "string", "readOnly": true, "nullable": true, "description": "Name of a routing policy to apply to every call made with this key (one of the key owner's own, or one of the organization's), or null for none." }, "revoked": { "type": "boolean", "readOnly": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "balance", "default_policy", "id", "masked", "member", "name", "revoked" ] }, "ManagementKeyCreateRequest": { "type": "object", "description": "Settings for a new API key.\n\n`name` must be unique among the owner's active keys. `me` and `base_token` are reserved, as are\nnames ending in `/rotate` or shaped `legacy//regenerate`; any other name, `/` included,\nis accepted. `token_type` selects the production\n(`api_token`) or sandbox (`sandbox_api_token`) environment and cannot be changed later.\n`member` attributes the key to an organization member so their usage is reported per user;\nomit it to create a service key attributed to the organization itself.\n\nSpending controls are optional: `balance` with `active_balance` caps what the key can spend,\n`expire_time` sets a hard expiry (at least one day ahead), and `balance_reset_period` with\n`balance_reset_amount` refills the balance on a schedule, and `budget_alert_percent` (1 to 100)\nemails the key's owner once per period when that share of the periodic budget is spent. The same\nrules apply as when creating a key from the dashboard.\n\n`default_tags` are up to 10 key/value strings added to every call made with the key; a tag the\ncall sends itself wins on the same key. Keys are 1 to 64 letters, digits or `- _ . : /`, stored\nlowercased; values are 1 to 128 of the same plus `@`, `+` and single spaces between words. The\n`eden:` key prefix is reserved.\n\n`default_policy` names a routing policy of the organization to apply to every call made with\nthe key (see `/v3/manage/routing-policies/`); omit it or send `null` for none.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "token_type": { "allOf": [ { "$ref": "#/components/schemas/ManagementKeyCreateTokenTypeEnum" } ], "default": "api_token" }, "member": { "type": "string", "format": "email", "minLength": 1 }, "balance": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,5}(?:\\.\\d{0,9})?$" }, "expire_time": { "type": "string", "format": "date-time" }, "active_balance": { "type": "boolean", "default": true }, "balance_reset_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,5}(?:\\.\\d{0,9})?$" }, "balance_reset_period": { "allOf": [ { "$ref": "#/components/schemas/BalanceResetPeriodEnum" } ], "default": "none" }, "budget_alert_percent": { "type": "integer", "maximum": 100, "minimum": 1, "nullable": true }, "default_tags": { "nullable": true }, "default_policy": { "type": "string", "nullable": true, "description": "Name of a routing policy to apply to every call made with this key (one of the key owner's own, or one of the organization's), or null for none." } }, "required": [ "name" ] }, "ManagementKeyCreateTokenTypeEnum": { "enum": [ "api_token", "sandbox_api_token" ], "type": "string", "description": "* `api_token` - api_token\n* `sandbox_api_token` - sandbox_api_token" }, "ManagementKeyIdentity": { "type": "object", "properties": { "organization_id": { "type": "integer" }, "organization_name": { "type": "string" }, "key_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "expires_at", "key_id", "name", "organization_id", "organization_name", "scopes" ] }, "ManagementKeyMintRequest": { "type": "object", "description": "Settings for a new management key: a display `name`, the `scopes` it grants, and an optional\n`expire_time` (omit it for a key that does not expire). `manage:read` and `manage:write` can be\ncombined; `manage:mint` is exclusive and can only be granted from the dashboard.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopesEnum" } }, "expire_time": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "name", "scopes" ] }, "ManagementKeyRead": { "type": "object", "description": "A management key of the organization. The secret is never included; `masked` shows the key\nprefix and last characters for identification. A revoked key has a non-null `revoked_at`.", "properties": { "key_id": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "maxLength": 200 }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopesEnum" } }, "masked": { "type": "string", "readOnly": true }, "expire_time": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "key_id", "masked", "name", "scopes" ] }, "MaxPrice": { "type": "object", "description": "A per-million-token ceiling; at least one of the two sides.", "properties": { "input": { "type": "number", "format": "double", "minimum": 0, "nullable": true }, "output": { "type": "number", "format": "double", "minimum": 0, "nullable": true } } }, "MaxPriceRequest": { "type": "object", "description": "A per-million-token ceiling; at least one of the two sides.", "properties": { "input": { "type": "number", "format": "double", "minimum": 0, "nullable": true }, "output": { "type": "number", "format": "double", "minimum": 0, "nullable": true } } }, "MintedManagementKey": { "type": "object", "description": "A freshly created API key. Identical to the key resource plus `secret`, the full key value.\nThe secret is shown only in this response and cannot be retrieved again; store it securely.", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "nullable": true }, "name": { "type": "string", "description": "The token name", "maxLength": 200 }, "token_type": { "$ref": "#/components/schemas/TokenTypeD53Enum" }, "member": { "type": "string", "format": "email", "readOnly": true }, "masked": { "type": "string", "readOnly": true }, "active_balance": { "type": "boolean", "description": "Weither to use the balance field or not." }, "balance": { "type": "number", "format": "double", "maximum": 100000, "minimum": -100000, "exclusiveMaximum": true, "exclusiveMinimum": true, "nullable": true, "readOnly": true }, "expire_time": { "type": "string", "format": "date-time", "nullable": true }, "default_tags": { "nullable": true, "description": "Tags added to every call made with this key. A tag the call sends itself wins on the same key." }, "default_policy": { "type": "string", "readOnly": true, "nullable": true, "description": "Name of a routing policy to apply to every call made with this key (one of the key owner's own, or one of the organization's), or null for none." }, "revoked": { "type": "boolean", "readOnly": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "secret": { "type": "string", "readOnly": true } }, "required": [ "balance", "default_policy", "id", "masked", "member", "name", "revoked", "secret" ] }, "NullEnum": { "enum": [ null ] }, "OrganisationUsers": { "type": "object", "description": "A member of the organization: identity, role, rate limits, directory groups and the API keys\nattributed to them (never their secrets).", "properties": { "email": { "type": "string", "format": "email", "nullable": true, "maxLength": 500 }, "fullname": { "type": "string", "pattern": "^[a-zA-Z\\'\\- ]+$", "maxLength": 60 }, "is_confirmed": { "type": "boolean" }, "role": { "type": "string", "readOnly": true }, "guardrail": { "type": "string", "readOnly": true }, "effective_rate_limit": { "type": "string", "readOnly": true }, "tokens": { "type": "string", "readOnly": true }, "is_org_owner": { "type": "boolean", "readOnly": true }, "directory_groups": { "type": "string", "readOnly": true } }, "required": [ "directory_groups", "effective_rate_limit", "fullname", "guardrail", "is_org_owner", "role", "tokens" ] }, "PaginatedManageGroupList": { "type": "object", "required": [ "results", "limit", "offset", "total_count", "next", "previous" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ManageGroup" } }, "limit": { "type": "integer", "example": 25, "description": "Page size applied to this response (max 100)." }, "offset": { "type": "integer", "example": 0, "description": "Index of the first item in this page." }, "total_count": { "type": "integer", "example": 123, "description": "Total number of items across all pages." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "https://api.edenai.run/v3/manage/members/?limit=25&offset=25", "description": "Absolute URL of the next page, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "description": "Absolute URL of the previous page, or null on the first page." } } }, "PaginatedManagementKeyList": { "type": "object", "required": [ "results", "limit", "offset", "total_count", "next", "previous" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ManagementKey" } }, "limit": { "type": "integer", "example": 25, "description": "Page size applied to this response (max 100)." }, "offset": { "type": "integer", "example": 0, "description": "Index of the first item in this page." }, "total_count": { "type": "integer", "example": 123, "description": "Total number of items across all pages." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "https://api.edenai.run/v3/manage/members/?limit=25&offset=25", "description": "Absolute URL of the next page, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "description": "Absolute URL of the previous page, or null on the first page." } } }, "PaginatedOrganisationUsersList": { "type": "object", "required": [ "results", "limit", "offset", "total_count", "next", "previous" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/OrganisationUsers" } }, "limit": { "type": "integer", "example": 25, "description": "Page size applied to this response (max 100)." }, "offset": { "type": "integer", "example": 0, "description": "Index of the first item in this page." }, "total_count": { "type": "integer", "example": 123, "description": "Total number of items across all pages." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "https://api.edenai.run/v3/manage/members/?limit=25&offset=25", "description": "Absolute URL of the next page, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "description": "Absolute URL of the previous page, or null on the first page." } } }, "PaginatedRoutingPolicyList": { "type": "object", "required": [ "results", "limit", "offset", "total_count", "next", "previous" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingPolicy" } }, "limit": { "type": "integer", "example": 25, "description": "Page size applied to this response (max 100)." }, "offset": { "type": "integer", "example": 0, "description": "Index of the first item in this page." }, "total_count": { "type": "integer", "example": 123, "description": "Total number of items across all pages." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "https://api.edenai.run/v3/manage/members/?limit=25&offset=25", "description": "Absolute URL of the next page, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "description": "Absolute URL of the previous page, or null on the first page." } } }, "PatchedManageMemberRoleRequest": { "type": "object", "description": "The role to assign, by id.", "properties": { "role_id": { "type": "integer" } } }, "PatchedManagementKeyUpdateRequest": { "type": "object", "description": "Editable API key fields: the display `name`, the spending controls and the `default_tags`.\nAll fields are optional; only the fields you send are changed. `default_tags` replaces the key's\ntags as a whole; send `null` or `{}` to remove them. The environment (`token_type`) cannot be\nchanged: create a new key instead. A new `name` follows the same rules as when creating a key,\nand renaming to a name already used by one of the owner's active keys returns 409.\n`default_policy` binds a routing policy of the organization by name; send `null` to unbind.", "properties": { "name": { "type": "string", "minLength": 1, "description": "The token name", "maxLength": 200 }, "active_balance": { "type": "boolean", "description": "Weither to use the balance field or not." }, "balance": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,5}(?:\\.\\d{0,9})?$", "nullable": true, "description": "Optional remaining credits balance for this Token, if `active_balance` is set to True and the balance reaches 0, this token will become unusable" }, "balance_reset_amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,5}(?:\\.\\d{0,9})?$", "nullable": true, "description": "The amount this token's balance is reset to at the start of each balance_reset_period. Null when balance_reset_period is 'none'." }, "balance_reset_period": { "allOf": [ { "$ref": "#/components/schemas/BalanceResetPeriodEnum" } ], "description": "How often this token's balance is reinitialized to balance_reset_amount. 'none' = one-time balance (default, current behaviour).\n\n* `none` - None\n* `daily` - Daily\n* `weekly` - Weekly\n* `monthly` - Monthly" }, "budget_alert_percent": { "type": "integer", "maximum": 100, "minimum": 1, "nullable": true, "description": "Alert the key owner by email when this % of the periodic budget is used." }, "default_tags": { "nullable": true, "description": "Tags added to every call made with this key. A tag the call sends itself wins on the same key." }, "default_policy": { "type": "string", "nullable": true, "description": "Name of a routing policy to apply to every call made with this key (one of the key owner's own, or one of the organization's), or null for none." } } }, "PolicyDefaults": { "type": "object", "description": "Settings applied to every target unless the target overrides them.", "properties": { "routing": { "$ref": "#/components/schemas/RoutingPreferences" }, "credentials": { "allOf": [ { "$ref": "#/components/schemas/CredentialsEnum" } ], "default": "auto" }, "retries": { "type": "integer", "maximum": 3, "minimum": 0, "default": 0 } } }, "PolicyDefaultsRequest": { "type": "object", "description": "Settings applied to every target unless the target overrides them.", "properties": { "routing": { "$ref": "#/components/schemas/RoutingPreferencesRequest" }, "credentials": { "allOf": [ { "$ref": "#/components/schemas/CredentialsEnum" } ], "default": "auto" }, "retries": { "type": "integer", "maximum": 3, "minimum": 0, "default": 0 } } }, "PolicyTarget": { "type": "object", "description": "One candidate model and its per-target overrides. A plain string is ``{\"model\": …}``.", "properties": { "model": { "type": "string" }, "weight": { "type": "integer", "maximum": 100, "minimum": 1 }, "retries": { "type": "integer", "maximum": 3, "minimum": 0 }, "credentials": { "$ref": "#/components/schemas/CredentialsEnum" }, "routing": { "$ref": "#/components/schemas/RoutingPreferences" }, "region": { "type": "string" } }, "required": [ "model" ] }, "PolicyTargetRequest": { "type": "object", "description": "One candidate model and its per-target overrides. A plain string is ``{\"model\": …}``.", "properties": { "model": { "type": "string", "minLength": 1 }, "weight": { "type": "integer", "maximum": 100, "minimum": 1 }, "retries": { "type": "integer", "maximum": 3, "minimum": 0 }, "credentials": { "$ref": "#/components/schemas/CredentialsEnum" }, "routing": { "$ref": "#/components/schemas/RoutingPreferencesRequest" }, "region": { "type": "string", "minLength": 1 } }, "required": [ "model" ] }, "RotatedApiKey": { "type": "object", "properties": { "secret": { "type": "string", "description": "The new key value. Shown only in this response; store it securely." }, "masked": { "type": "string" }, "name": { "type": "string" } }, "required": [ "masked", "name", "secret" ] }, "RoutingPolicy": { "type": "object", "description": "A routing policy as the management API returns it.", "properties": { "name": { "type": "string", "readOnly": true }, "scope": { "allOf": [ { "$ref": "#/components/schemas/ScopeEnum" } ], "readOnly": true, "description": "`organization` for a shared policy, `user` for a personal one.\n\n* `organization` - Organization\n* `user` - User" }, "description": { "type": "string", "readOnly": true }, "enabled": { "type": "boolean", "readOnly": true }, "strategy": { "readOnly": true, "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/StrategyEnum" }, { "$ref": "#/components/schemas/NullEnum" } ] }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyTarget" }, "nullable": true, "readOnly": true }, "defaults": { "allOf": [ { "$ref": "#/components/schemas/PolicyDefaults" } ], "readOnly": true }, "lock": { "type": "array", "items": { "$ref": "#/components/schemas/LockEnum" }, "readOnly": true }, "fallbacks": { "type": "array", "items": { "type": "string" }, "readOnly": true }, "version": { "type": "integer", "readOnly": true }, "etag": { "type": "string", "readOnly": true, "description": "The version, as the `If-Match` header expects it." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "format": "email", "readOnly": true, "nullable": true, "description": "Email of the creator, or null for an API write." }, "updated_by": { "type": "string", "format": "email", "readOnly": true, "nullable": true, "description": "Email of the last editor, or null for an API write." } }, "required": [ "created_at", "created_by", "defaults", "description", "enabled", "etag", "fallbacks", "lock", "name", "scope", "strategy", "targets", "updated_at", "updated_by", "version" ] }, "RoutingPolicyBodyRequest": { "type": "object", "description": "The body of a `PUT` on a routing policy: what the policy tries and how, its defaults,\nits locked fields and its last-resort fallbacks.", "properties": { "description": { "type": "string", "default": "", "maxLength": 500 }, "enabled": { "type": "boolean", "default": true }, "strategy": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/StrategyEnum" }, { "$ref": "#/components/schemas/NullEnum" } ] }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyTargetRequest" }, "nullable": true, "maxItems": 32, "minItems": 1 }, "defaults": { "$ref": "#/components/schemas/PolicyDefaultsRequest" }, "lock": { "type": "array", "items": { "$ref": "#/components/schemas/LockEnum" } }, "fallbacks": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 7 } } }, "RoutingPreferences": { "type": "object", "description": "The request ``routing`` object as a policy stores it. A ``null`` means unset: the\nfield then comes from the request or the platform default.", "properties": { "sort": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/SortEnum" }, { "$ref": "#/components/schemas/NullEnum" } ] }, "sticky": { "type": "boolean", "nullable": true }, "allow_fallbacks": { "type": "boolean", "nullable": true }, "allowed_providers": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "nullable": true }, "ignored_providers": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "nullable": true }, "order": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "nullable": true, "maxItems": 16 }, "max_price": { "allOf": [ { "$ref": "#/components/schemas/MaxPrice" } ], "nullable": true }, "zero_data_retention": { "type": "boolean", "nullable": true } } }, "RoutingPreferencesRequest": { "type": "object", "description": "The request ``routing`` object as a policy stores it. A ``null`` means unset: the\nfield then comes from the request or the platform default.", "properties": { "sort": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/SortEnum" }, { "$ref": "#/components/schemas/NullEnum" } ] }, "sticky": { "type": "boolean", "nullable": true }, "allow_fallbacks": { "type": "boolean", "nullable": true }, "allowed_providers": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "nullable": true }, "ignored_providers": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "nullable": true }, "order": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "nullable": true, "maxItems": 16 }, "max_price": { "allOf": [ { "$ref": "#/components/schemas/MaxPriceRequest" } ], "nullable": true }, "zero_data_retention": { "type": "boolean", "nullable": true } } }, "ScopeEnum": { "enum": [ "organization", "user" ], "type": "string", "description": "* `organization` - Organization\n* `user` - User" }, "ScopesEnum": { "enum": [ "manage:read", "manage:write", "manage:mint" ], "type": "string", "description": "* `manage:read` - Read organization members, keys and usage\n* `manage:write` - Create, update and revoke keys and members\n* `manage:mint` - Issue new worker management keys (issuer key)" }, "SortEnum": { "enum": [ "cost", "speed", "latency", "exact" ], "type": "string", "description": "* `cost` - cost\n* `speed` - speed\n* `latency` - latency\n* `exact` - exact" }, "StrategyEnum": { "enum": [ "fallback", "load_balance", "cheapest", "fastest" ], "type": "string", "description": "* `fallback` - Fallback\n* `load_balance` - Load balance\n* `cheapest` - Cheapest\n* `fastest` - Fastest" }, "TokenData": { "properties": { "token": { "title": "Token", "type": "string" }, "data": { "additionalProperties": { "additionalProperties": { "$ref": "#/components/schemas/Details" }, "type": "object" }, "title": "Data", "type": "object" } }, "required": [ "token", "data" ], "title": "TokenData", "type": "object" }, "TokenTypeD53Enum": { "enum": [ "sandbox_api_token", "api_token" ], "type": "string", "description": "* `sandbox_api_token` - Sandbox\n* `api_token` - Back" }, "UserCostTotal": { "description": "Total cost of one member over the window.", "properties": { "user": { "title": "User", "type": "string" }, "total_cost": { "title": "Total Cost", "type": "number" } }, "required": [ "user", "total_cost" ], "title": "UserCostTotal", "type": "object" } }, "securitySchemes": { "ManagementKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "A management key (created from the organization dashboard or with `POST /v3/manage/auth-keys`), sent as `Authorization: Bearer `. Inference API keys (`sk-eden...`) are not accepted on these endpoints." }, "ManagementKeyOrUserAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "A management key (`mgmt-eden...`) to manage the organization's routing policies, or your own API key (`sk-eden...`) or session token to manage your personal ones, sent as `Authorization: Bearer `." } } }, "servers": [ { "url": "https://api.edenai.run" } ] }