diff --git a/async-openai/README.md b/async-openai/README.md index 3a266ba8..a5a8f624 100644 --- a/async-openai/README.md +++ b/async-openai/README.md @@ -32,13 +32,13 @@ | **Realtime** | Realtime Calls, Client secrets, Client events, Server events | | **Chat Completions** | Chat Completions, Streaming | | **Assistants** (Beta) | Assistants, Threads, Messages, Runs, Run steps, Streaming | -| **Administration** | Admin API Keys, Invites, Users, Projects, Project users, Project service accounts, Project API keys, Project rate limits, Audit logs, Usage, Certificates | +| **Administration** | Admin API Keys, Invites, Users, Groups, Roles, Role assignments, Projects, Project users, Project groups, Project service accounts, Project API keys, Project rate limits, Audit logs, Usage, Certificates | | **Legacy** | Completions | Features that makes `async-openai` unique: - Bring your own custom types for Request or Response objects. - SSE streaming on available APIs. -- Customize query and headers per request, customize headers globally. +- Customize path, query and headers per request; customize path and headers globally (for all requests). - Requests (except SSE streaming) including form submissions are retried with exponential backoff when [rate limited](https://platform.openai.com/docs/guides/rate-limits). - Ergonomic builder pattern for all request objects. - Microsoft Azure OpenAI Service (only for APIs matching OpenAI spec). diff --git a/async-openai/src/admin.rs b/async-openai/src/admin.rs index 5372775c..06dfb469 100644 --- a/async-openai/src/admin.rs +++ b/async-openai/src/admin.rs @@ -1,10 +1,11 @@ use crate::{ admin_api_keys::AdminAPIKeys, audit_logs::AuditLogs, certificates::Certificates, - config::Config, invites::Invites, projects::Projects, users::Users, Client, + config::Config, groups::Groups, invites::Invites, projects::Projects, roles::Roles, + users::Users, Client, }; /// Admin group for all administration APIs. -/// This groups together admin API keys, invites, users, projects, audit logs, and certificates. +/// This groups together admin API keys, invites, users, projects, audit logs, certificates, roles, and groups. pub struct Admin<'c, C: Config> { client: &'c Client, } @@ -43,4 +44,14 @@ impl<'c, C: Config> Admin<'c, C> { pub fn certificates(&self) -> Certificates<'_, C> { Certificates::new(self.client) } + + /// To call [Roles] group related APIs using this client. + pub fn roles(&self) -> Roles<'_, C> { + Roles::new(self.client) + } + + /// To call [Groups] group related APIs using this client. + pub fn groups(&self) -> Groups<'_, C> { + Groups::new(self.client) + } } diff --git a/async-openai/src/group_roles.rs b/async-openai/src/group_roles.rs new file mode 100644 index 00000000..1fccd59d --- /dev/null +++ b/async-openai/src/group_roles.rs @@ -0,0 +1,64 @@ +use crate::{ + config::Config, + error::OpenAIError, + types::admin::groups::{GroupRoleAssignment, PublicAssignOrganizationGroupRoleBody}, + types::admin::roles::{DeletedRoleAssignmentResource, RoleListResource}, + Client, RequestOptions, +}; + +/// Manage role assignments for groups in the organization. +pub struct GroupRoles<'c, C: Config> { + client: &'c Client, + pub group_id: String, + pub(crate) request_options: RequestOptions, +} + +impl<'c, C: Config> GroupRoles<'c, C> { + pub fn new(client: &'c Client, group_id: &str) -> Self { + Self { + client, + group_id: group_id.into(), + request_options: RequestOptions::new(), + } + } + + /// Lists all role assignments for a group. + #[crate::byot(R = serde::de::DeserializeOwned)] + pub async fn list(&self) -> Result { + self.client + .get( + format!("/organization/groups/{}/roles", self.group_id).as_str(), + &self.request_options, + ) + .await + } + + /// Assigns a role to a group. + #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn assign( + &self, + request: PublicAssignOrganizationGroupRoleBody, + ) -> Result { + self.client + .post( + format!("/organization/groups/{}/roles", self.group_id).as_str(), + request, + &self.request_options, + ) + .await + } + + /// Unassigns a role from a group. + #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)] + pub async fn unassign( + &self, + role_id: &str, + ) -> Result { + self.client + .delete( + format!("/organization/groups/{}/roles/{}", self.group_id, role_id).as_str(), + &self.request_options, + ) + .await + } +} diff --git a/async-openai/src/group_users.rs b/async-openai/src/group_users.rs new file mode 100644 index 00000000..8cd37cab --- /dev/null +++ b/async-openai/src/group_users.rs @@ -0,0 +1,62 @@ +use crate::{ + config::Config, + error::OpenAIError, + types::admin::groups::{ + CreateGroupUserBody, GroupUserAssignment, GroupUserDeletedResource, UserListResource, + }, + Client, RequestOptions, +}; + +/// Manage users within a group, including adding and removing users. +pub struct GroupUsers<'c, C: Config> { + client: &'c Client, + pub group_id: String, + pub(crate) request_options: RequestOptions, +} + +impl<'c, C: Config> GroupUsers<'c, C> { + pub fn new(client: &'c Client, group_id: &str) -> Self { + Self { + client, + group_id: group_id.into(), + request_options: RequestOptions::new(), + } + } + + /// Lists all users in a group. + #[crate::byot(R = serde::de::DeserializeOwned)] + pub async fn list(&self) -> Result { + self.client + .get( + format!("/organization/groups/{}/users", self.group_id).as_str(), + &self.request_options, + ) + .await + } + + /// Adds a user to a group. + #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn add( + &self, + request: CreateGroupUserBody, + ) -> Result { + self.client + .post( + format!("/organization/groups/{}/users", self.group_id).as_str(), + request, + &self.request_options, + ) + .await + } + + /// Removes a user from a group. + #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)] + pub async fn remove(&self, user_id: &str) -> Result { + self.client + .delete( + format!("/organization/groups/{}/users/{user_id}", self.group_id).as_str(), + &self.request_options, + ) + .await + } +} diff --git a/async-openai/src/groups.rs b/async-openai/src/groups.rs new file mode 100644 index 00000000..c15e599b --- /dev/null +++ b/async-openai/src/groups.rs @@ -0,0 +1,79 @@ +use crate::{ + config::Config, + error::OpenAIError, + group_roles::GroupRoles, + group_users::GroupUsers, + types::admin::groups::{ + CreateGroupBody, GroupDeletedResource, GroupListResource, GroupResourceWithSuccess, + GroupResponse, + }, + Client, RequestOptions, +}; + +/// Manage reusable collections of users for organization-wide access control and maintain their membership. +pub struct Groups<'c, C: Config> { + client: &'c Client, + pub(crate) request_options: RequestOptions, +} + +impl<'c, C: Config> Groups<'c, C> { + pub fn new(client: &'c Client) -> Self { + Self { + client, + request_options: RequestOptions::new(), + } + } + + /// To call [GroupUsers] group related APIs using this client. + pub fn users(&self, group_id: &str) -> GroupUsers<'_, C> { + GroupUsers::new(self.client, group_id) + } + + /// To call [GroupRoles] group related APIs using this client. + pub fn roles(&self, group_id: &str) -> GroupRoles<'_, C> { + GroupRoles::new(self.client, group_id) + } + + /// Lists all groups in the organization. + #[crate::byot(R = serde::de::DeserializeOwned)] + pub async fn list(&self) -> Result { + self.client + .get("/organization/groups", &self.request_options) + .await + } + + /// Creates a new group in the organization. + #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn create(&self, request: CreateGroupBody) -> Result { + self.client + .post("/organization/groups", request, &self.request_options) + .await + } + + /// Updates a group's information. + #[crate::byot(T0 = std::fmt::Display, T1 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn update( + &self, + group_id: &str, + request: crate::types::admin::groups::UpdateGroupBody, + ) -> Result { + self.client + .post( + format!("/organization/groups/{group_id}").as_str(), + request, + &self.request_options, + ) + .await + } + + /// Deletes a group from the organization. + #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)] + pub async fn delete(&self, group_id: &str) -> Result { + self.client + .delete( + format!("/organization/groups/{group_id}").as_str(), + &self.request_options, + ) + .await + } +} diff --git a/async-openai/src/lib.rs b/async-openai/src/lib.rs index 4ea77473..200ac49f 100644 --- a/async-openai/src/lib.rs +++ b/async-openai/src/lib.rs @@ -164,6 +164,9 @@ mod eval_runs; mod evals; mod file; mod fine_tuning; +mod group_roles; +mod group_users; +mod groups; mod image; mod invites; mod messages; @@ -171,14 +174,19 @@ mod model; mod moderation; mod project_api_keys; mod project_certificates; +mod project_group_roles; +mod project_groups; mod project_rate_limits; +mod project_roles; mod project_service_accounts; +mod project_user_roles; mod project_users; mod projects; #[cfg(feature = "realtime")] mod realtime; mod request_options; mod responses; +mod roles; mod runs; mod speech; mod steps; @@ -189,6 +197,7 @@ mod translations; pub mod types; mod uploads; mod usage; +mod user_roles; mod users; mod util; mod vector_store_file_batches; @@ -219,6 +228,9 @@ pub use eval_runs::EvalRuns; pub use evals::Evals; pub use file::Files; pub use fine_tuning::FineTuning; +pub use group_roles::GroupRoles; +pub use group_users::GroupUsers; +pub use groups::Groups; pub use image::Images; pub use invites::Invites; pub use messages::Messages; @@ -226,14 +238,19 @@ pub use model::Models; pub use moderation::Moderations; pub use project_api_keys::ProjectAPIKeys; pub use project_certificates::ProjectCertificates; +pub use project_group_roles::ProjectGroupRoles; +pub use project_groups::ProjectGroups; pub use project_rate_limits::ProjectRateLimits; +pub use project_roles::ProjectRoles; pub use project_service_accounts::ProjectServiceAccounts; +pub use project_user_roles::ProjectUserRoles; pub use project_users::ProjectUsers; pub use projects::Projects; #[cfg(feature = "realtime")] pub use realtime::Realtime; pub use request_options::RequestOptions; pub use responses::Responses; +pub use roles::Roles; pub use runs::Runs; pub use speech::Speech; pub use steps::Steps; @@ -242,6 +259,7 @@ pub use transcriptions::Transcriptions; pub use translations::Translations; pub use uploads::Uploads; pub use usage::Usage; +pub use user_roles::UserRoles; pub use users::Users; pub use vector_store_file_batches::VectorStoreFileBatches; pub use vector_store_files::VectorStoreFiles; diff --git a/async-openai/src/project_group_roles.rs b/async-openai/src/project_group_roles.rs new file mode 100644 index 00000000..dbb9bc8a --- /dev/null +++ b/async-openai/src/project_group_roles.rs @@ -0,0 +1,78 @@ +use crate::{ + config::Config, + error::OpenAIError, + types::admin::groups::{GroupRoleAssignment, PublicAssignOrganizationGroupRoleBody}, + types::admin::roles::{DeletedRoleAssignmentResource, RoleListResource}, + Client, RequestOptions, +}; + +/// Manage role assignments for groups in a project. +pub struct ProjectGroupRoles<'c, C: Config> { + client: &'c Client, + pub project_id: String, + pub group_id: String, + pub(crate) request_options: RequestOptions, +} + +impl<'c, C: Config> ProjectGroupRoles<'c, C> { + pub fn new(client: &'c Client, project_id: &str, group_id: &str) -> Self { + Self { + client, + project_id: project_id.into(), + group_id: group_id.into(), + request_options: RequestOptions::new(), + } + } + + /// Lists all role assignments for a group in the project. + #[crate::byot(R = serde::de::DeserializeOwned)] + pub async fn list(&self) -> Result { + self.client + .get( + format!( + "/projects/{}/groups/{}/roles", + self.project_id, self.group_id + ) + .as_str(), + &self.request_options, + ) + .await + } + + /// Assigns a role to a group in the project. + #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn assign( + &self, + request: PublicAssignOrganizationGroupRoleBody, + ) -> Result { + self.client + .post( + format!( + "/projects/{}/groups/{}/roles", + self.project_id, self.group_id + ) + .as_str(), + request, + &self.request_options, + ) + .await + } + + /// Unassigns a role from a group in the project. + #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)] + pub async fn unassign( + &self, + role_id: &str, + ) -> Result { + self.client + .delete( + format!( + "/projects/{}/groups/{}/roles/{}", + self.project_id, self.group_id, role_id + ) + .as_str(), + &self.request_options, + ) + .await + } +} diff --git a/async-openai/src/project_groups.rs b/async-openai/src/project_groups.rs new file mode 100644 index 00000000..601b1076 --- /dev/null +++ b/async-openai/src/project_groups.rs @@ -0,0 +1,63 @@ +use crate::{ + config::Config, + error::OpenAIError, + types::admin::projects::{ + InviteProjectGroupBody, ProjectGroup, ProjectGroupDeletedResource, ProjectGroupListResource, + }, + Client, RequestOptions, +}; + +/// Manage which groups have access to a project and the role they receive. +pub struct ProjectGroups<'c, C: Config> { + client: &'c Client, + pub project_id: String, + pub(crate) request_options: RequestOptions, +} + +impl<'c, C: Config> ProjectGroups<'c, C> { + pub fn new(client: &'c Client, project_id: &str) -> Self { + Self { + client, + project_id: project_id.into(), + request_options: RequestOptions::new(), + } + } + + /// Lists all groups that have access to a project. + #[crate::byot(R = serde::de::DeserializeOwned)] + pub async fn list(&self) -> Result { + self.client + .get( + format!("/organization/projects/{}/groups", self.project_id).as_str(), + &self.request_options, + ) + .await + } + + /// Grants a group access to a project. + #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn add(&self, request: InviteProjectGroupBody) -> Result { + self.client + .post( + format!("/organization/projects/{}/groups", self.project_id).as_str(), + request, + &self.request_options, + ) + .await + } + + /// Removes a group from a project. + #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)] + pub async fn remove(&self, group_id: &str) -> Result { + self.client + .delete( + format!( + "/organization/projects/{}/groups/{group_id}", + self.project_id + ) + .as_str(), + &self.request_options, + ) + .await + } +} diff --git a/async-openai/src/project_roles.rs b/async-openai/src/project_roles.rs new file mode 100644 index 00000000..43306a8f --- /dev/null +++ b/async-openai/src/project_roles.rs @@ -0,0 +1,79 @@ +use crate::{ + config::Config, + error::OpenAIError, + types::admin::roles::{ + PublicCreateOrganizationRoleBody, PublicRoleListResource, PublicUpdateOrganizationRoleBody, + Role, RoleDeletedResource, + }, + Client, RequestOptions, +}; + +/// Manage custom roles that can be assigned to groups and users at the project level. +pub struct ProjectRoles<'c, C: Config> { + client: &'c Client, + pub project_id: String, + pub(crate) request_options: RequestOptions, +} + +impl<'c, C: Config> ProjectRoles<'c, C> { + pub fn new(client: &'c Client, project_id: &str) -> Self { + Self { + client, + project_id: project_id.into(), + request_options: RequestOptions::new(), + } + } + + /// Lists the roles configured for the project. + #[crate::byot(R = serde::de::DeserializeOwned)] + pub async fn list(&self) -> Result { + self.client + .get( + format!("/projects/{}/roles", self.project_id).as_str(), + &self.request_options, + ) + .await + } + + /// Creates a custom role for the project. + #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn create( + &self, + request: PublicCreateOrganizationRoleBody, + ) -> Result { + self.client + .post( + format!("/projects/{}/roles", self.project_id).as_str(), + request, + &self.request_options, + ) + .await + } + + /// Updates an existing project role. + #[crate::byot(T0 = std::fmt::Display, T1 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn update( + &self, + role_id: &str, + request: PublicUpdateOrganizationRoleBody, + ) -> Result { + self.client + .post( + format!("/projects/{}/roles/{}", self.project_id, role_id).as_str(), + request, + &self.request_options, + ) + .await + } + + /// Deletes a custom role from the project. + #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)] + pub async fn delete(&self, role_id: &str) -> Result { + self.client + .delete( + format!("/projects/{}/roles/{}", self.project_id, role_id).as_str(), + &self.request_options, + ) + .await + } +} diff --git a/async-openai/src/project_user_roles.rs b/async-openai/src/project_user_roles.rs new file mode 100644 index 00000000..6217c578 --- /dev/null +++ b/async-openai/src/project_user_roles.rs @@ -0,0 +1,71 @@ +use crate::{ + config::Config, + error::OpenAIError, + types::admin::groups::PublicAssignOrganizationGroupRoleBody, + types::admin::roles::{DeletedRoleAssignmentResource, RoleListResource}, + types::admin::users::UserRoleAssignment, + Client, RequestOptions, +}; + +/// Manage role assignments for users in a project. +pub struct ProjectUserRoles<'c, C: Config> { + client: &'c Client, + pub project_id: String, + pub user_id: String, + pub(crate) request_options: RequestOptions, +} + +impl<'c, C: Config> ProjectUserRoles<'c, C> { + pub fn new(client: &'c Client, project_id: &str, user_id: &str) -> Self { + Self { + client, + project_id: project_id.into(), + user_id: user_id.into(), + request_options: RequestOptions::new(), + } + } + + /// Lists all role assignments for a user in the project. + #[crate::byot(R = serde::de::DeserializeOwned)] + pub async fn list(&self) -> Result { + self.client + .get( + format!("/projects/{}/users/{}/roles", self.project_id, self.user_id).as_str(), + &self.request_options, + ) + .await + } + + /// Assigns a role to a user in the project. + #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn assign( + &self, + request: PublicAssignOrganizationGroupRoleBody, + ) -> Result { + self.client + .post( + format!("/projects/{}/users/{}/roles", self.project_id, self.user_id).as_str(), + request, + &self.request_options, + ) + .await + } + + /// Unassigns a role from a user in the project. + #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)] + pub async fn unassign( + &self, + role_id: &str, + ) -> Result { + self.client + .delete( + format!( + "/projects/{}/users/{}/roles/{}", + self.project_id, self.user_id, role_id + ) + .as_str(), + &self.request_options, + ) + .await + } +} diff --git a/async-openai/src/projects.rs b/async-openai/src/projects.rs index 6874775d..47277e49 100644 --- a/async-openai/src/projects.rs +++ b/async-openai/src/projects.rs @@ -3,7 +3,11 @@ use crate::{ error::OpenAIError, project_api_keys::ProjectAPIKeys, project_certificates::ProjectCertificates, + project_group_roles::ProjectGroupRoles, + project_groups::ProjectGroups, project_rate_limits::ProjectRateLimits, + project_roles::ProjectRoles, + project_user_roles::ProjectUserRoles, types::admin::projects::{ Project, ProjectCreateRequest, ProjectListResponse, ProjectUpdateRequest, }, @@ -50,6 +54,26 @@ impl<'c, C: Config> Projects<'c, C> { ProjectCertificates::new(self.client, project_id) } + // call [ProjectGroups] group APIs + pub fn groups(&self, project_id: &str) -> ProjectGroups<'_, C> { + ProjectGroups::new(self.client, project_id) + } + + // call [ProjectRoles] group APIs + pub fn roles(&self, project_id: &str) -> ProjectRoles<'_, C> { + ProjectRoles::new(self.client, project_id) + } + + // call [ProjectUserRoles] group APIs + pub fn user_roles(&self, project_id: &str, user_id: &str) -> ProjectUserRoles<'_, C> { + ProjectUserRoles::new(self.client, project_id, user_id) + } + + // call [ProjectGroupRoles] group APIs + pub fn group_roles(&self, project_id: &str, group_id: &str) -> ProjectGroupRoles<'_, C> { + ProjectGroupRoles::new(self.client, project_id, group_id) + } + /// Returns a list of projects. #[crate::byot(R = serde::de::DeserializeOwned)] pub async fn list(&self) -> Result { diff --git a/async-openai/src/roles.rs b/async-openai/src/roles.rs new file mode 100644 index 00000000..cf102c1c --- /dev/null +++ b/async-openai/src/roles.rs @@ -0,0 +1,70 @@ +use crate::{ + config::Config, + error::OpenAIError, + types::admin::roles::{ + PublicCreateOrganizationRoleBody, PublicRoleListResource, PublicUpdateOrganizationRoleBody, + Role, RoleDeletedResource, + }, + Client, RequestOptions, +}; + +/// Manage custom roles that can be assigned to groups and users at the organization or project level. +pub struct Roles<'c, C: Config> { + client: &'c Client, + pub(crate) request_options: RequestOptions, +} + +impl<'c, C: Config> Roles<'c, C> { + pub fn new(client: &'c Client) -> Self { + Self { + client, + request_options: RequestOptions::new(), + } + } + + /// Lists the roles configured for the organization. + #[crate::byot(R = serde::de::DeserializeOwned)] + pub async fn list(&self) -> Result { + self.client + .get("/organization/roles", &self.request_options) + .await + } + + /// Creates a custom role for the organization. + #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn create( + &self, + request: PublicCreateOrganizationRoleBody, + ) -> Result { + self.client + .post("/organization/roles", request, &self.request_options) + .await + } + + /// Updates an existing organization role. + #[crate::byot(T0 = std::fmt::Display, T1 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn update( + &self, + role_id: &str, + request: PublicUpdateOrganizationRoleBody, + ) -> Result { + self.client + .post( + format!("/organization/roles/{role_id}").as_str(), + request, + &self.request_options, + ) + .await + } + + /// Deletes a custom role from the organization. + #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)] + pub async fn delete(&self, role_id: &str) -> Result { + self.client + .delete( + format!("/organization/roles/{role_id}").as_str(), + &self.request_options, + ) + .await + } +} diff --git a/async-openai/src/types/admin/groups.rs b/async-openai/src/types/admin/groups.rs new file mode 100644 index 00000000..4581df54 --- /dev/null +++ b/async-openai/src/types/admin/groups.rs @@ -0,0 +1,204 @@ +use crate::types::admin::roles::Role; +use crate::types::admin::users::User; +use crate::types::OpenAIError; +use derive_builder::Builder; +use serde::{Deserialize, Serialize}; + +/// Sort order for listing groups. +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] +#[serde(rename_all = "lowercase")] +pub enum ListGroupsOrder { + /// Ascending order + Asc, + /// Descending order + Desc, +} + +/// Query parameters for listing groups. +#[derive(Debug, Serialize, Default, Clone, Builder, PartialEq)] +#[builder(name = "ListGroupsQueryArgs")] +#[builder(pattern = "mutable")] +#[builder(setter(into, strip_option), default)] +#[builder(derive(Debug))] +#[builder(build_fn(error = "OpenAIError"))] +pub struct ListGroupsQuery { + /// A limit on the number of groups to be returned. Limit can range between 0 and 1000, and the default is 100. + #[serde(skip_serializing_if = "Option::is_none")] + pub limit: Option, + /// A cursor for use in pagination. `after` is a group ID that defines your place in the list. + #[serde(skip_serializing_if = "Option::is_none")] + pub after: Option, + /// Specifies the sort order of the returned groups. + #[serde(skip_serializing_if = "Option::is_none")] + pub order: Option, +} + +/// Summary information about a group returned in role assignment responses. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct Group { + /// The object type, which is always `group`. + pub object: String, + /// Identifier for the group. + pub id: String, + /// Display name of the group. + pub name: String, + /// Unix timestamp (in seconds) when the group was created. + pub created_at: u64, + /// Whether the group is managed through SCIM. + pub scim_managed: bool, +} + +/// Details about an organization group. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct GroupResponse { + /// Identifier for the group. + pub id: String, + /// Display name of the group. + pub name: String, + /// Unix timestamp (in seconds) when the group was created. + pub created_at: u64, + /// Whether the group is managed through SCIM and controlled by your identity provider. + pub is_scim_managed: bool, +} + +/// Paginated list of organization groups. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct GroupListResource { + /// The object type, which is always `list`. + pub object: String, + /// Groups returned in the current page. + pub data: Vec, + /// Whether additional groups are available when paginating. + pub has_more: bool, + /// Cursor to fetch the next page of results, or `null` if there are no more results. + pub next: Option, +} + +/// Confirmation payload returned after deleting a group. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct GroupDeletedResource { + /// The object type, which is always `group.deleted`. + pub object: String, + /// Identifier of the deleted group. + pub id: String, + /// Whether the group was deleted. + pub deleted: bool, +} + +/// Response returned after updating a group. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct GroupResourceWithSuccess { + /// Identifier for the group. + pub id: String, + /// Updated display name for the group. + pub name: String, + /// Unix timestamp (in seconds) when the group was created. + pub created_at: u64, + /// Whether the group is managed through SCIM and controlled by your identity provider. + pub is_scim_managed: bool, +} + +/// Request payload for creating a new group in the organization. +#[derive(Debug, Serialize, Deserialize, Builder, Clone, PartialEq)] +#[builder(name = "CreateGroupRequestArgs")] +#[builder(pattern = "mutable")] +#[builder(setter(into, strip_option))] +#[builder(derive(Debug))] +#[builder(build_fn(error = "OpenAIError"))] +pub struct CreateGroupBody { + /// Human readable name for the group. + pub name: String, +} + +/// Request payload for updating the details of an existing group. +#[derive(Debug, Serialize, Deserialize, Builder, Clone, PartialEq)] +#[builder(name = "UpdateGroupRequestArgs")] +#[builder(pattern = "mutable")] +#[builder(setter(into, strip_option))] +#[builder(derive(Debug))] +#[builder(build_fn(error = "OpenAIError"))] +pub struct UpdateGroupBody { + /// New display name for the group. + pub name: String, +} + +/// Request payload for adding a user to a group. +#[derive(Debug, Serialize, Deserialize, Builder, Clone, PartialEq)] +#[builder(name = "CreateGroupUserRequestArgs")] +#[builder(pattern = "mutable")] +#[builder(setter(into, strip_option))] +#[builder(derive(Debug))] +#[builder(build_fn(error = "OpenAIError"))] +pub struct CreateGroupUserBody { + /// Identifier of the user to add to the group. + pub user_id: String, +} + +/// Confirmation payload returned after adding a user to a group. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct GroupUserAssignment { + /// The object type, which is always `group.user`. + pub object: String, + /// Identifier of the user that was added. + pub user_id: String, + /// Identifier of the group the user was added to. + pub group_id: String, +} + +/// Confirmation payload returned after removing a user from a group. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct GroupUserDeletedResource { + /// The object type, which is always `group.user.deleted`. + pub object: String, + /// Whether the group membership was removed. + pub deleted: bool, +} + +/// Role assignment linking a group to a role. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct GroupRoleAssignment { + /// The object type, which is always `group.role`. + pub object: String, + /// The group. + pub group: Group, + /// The role. + pub role: Role, +} + +/// Paginated list of role assignments for a group. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct GroupRoleAssignmentListResource { + /// The object type, which is always `list`. + pub object: String, + /// Role assignments returned in the current page. + pub data: Vec, + /// Whether additional assignments are available when paginating. + pub has_more: bool, + /// Cursor to fetch the next page of results, or `null` when there are no more assignments. + pub next: Option, +} + +/// Request payload for assigning a role to a group. +#[derive(Debug, Serialize, Deserialize, Builder, Clone, PartialEq)] +#[builder(name = "AssignGroupRoleRequestArgs")] +#[builder(pattern = "mutable")] +#[builder(setter(into, strip_option))] +#[builder(derive(Debug))] +#[builder(build_fn(error = "OpenAIError"))] +pub struct PublicAssignOrganizationGroupRoleBody { + /// Identifier of the role to assign. + pub role_id: String, +} + +/// Paginated list of user objects returned when inspecting group membership. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct UserListResource { + /// The object type, which is always `list`. + pub object: String, + /// Users in the current page. + pub data: Vec, + /// Whether more users are available when paginating. + pub has_more: bool, + /// Cursor to fetch the next page of results, or `null` when no further users are available. + pub next: Option, +} diff --git a/async-openai/src/types/admin/mod.rs b/async-openai/src/types/admin/mod.rs index 396f3ca5..e5710916 100644 --- a/async-openai/src/types/admin/mod.rs +++ b/async-openai/src/types/admin/mod.rs @@ -3,11 +3,13 @@ pub mod api_keys; pub mod audit_logs; pub mod certificates; +pub mod groups; pub mod invites; pub mod project_api_keys; pub mod project_rate_limits; pub mod project_service_accounts; pub mod project_users; pub mod projects; +pub mod roles; pub mod usage; pub mod users; diff --git a/async-openai/src/types/admin/projects.rs b/async-openai/src/types/admin/projects.rs index 1a8189d7..4e06c43a 100644 --- a/async-openai/src/types/admin/projects.rs +++ b/async-openai/src/types/admin/projects.rs @@ -79,3 +79,54 @@ pub struct ProjectUpdateRequest { /// The updated name of the project, this name appears in reports. pub name: String, } + +/// Details about a group's membership in a project. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct ProjectGroup { + /// The object type, which is always `project.group`. + pub object: String, + /// Identifier of the project. + pub project_id: String, + /// Identifier of the group that has access to the project. + pub group_id: String, + /// Display name of the group. + pub group_name: String, + /// Unix timestamp (in seconds) when the group was granted project access. + pub created_at: u64, +} + +/// Paginated list of groups that have access to a project. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct ProjectGroupListResource { + /// The object type, which is always `list`. + pub object: String, + /// Project group memberships returned in the current page. + pub data: Vec, + /// Whether additional project group memberships are available. + pub has_more: bool, + /// Cursor to fetch the next page of results, or `null` when there are no more results. + pub next: Option, +} + +/// Confirmation payload returned after removing a group from a project. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct ProjectGroupDeletedResource { + /// The object type, which is always `project.group.deleted`. + pub object: String, + /// Whether the group membership in the project was removed. + pub deleted: bool, +} + +/// Request payload for granting a group access to a project. +#[derive(Debug, Serialize, Deserialize, Builder, Clone, PartialEq)] +#[builder(name = "InviteProjectGroupRequestArgs")] +#[builder(pattern = "mutable")] +#[builder(setter(into, strip_option))] +#[builder(derive(Debug))] +#[builder(build_fn(error = "OpenAIError"))] +pub struct InviteProjectGroupBody { + /// Identifier of the group to add to the project. + pub group_id: String, + /// Identifier of the project role to grant to the group. + pub role: String, +} diff --git a/async-openai/src/types/admin/roles.rs b/async-openai/src/types/admin/roles.rs new file mode 100644 index 00000000..5b92379c --- /dev/null +++ b/async-openai/src/types/admin/roles.rs @@ -0,0 +1,162 @@ +use crate::types::OpenAIError; +use derive_builder::Builder; +use serde::{Deserialize, Serialize}; + +/// Sort order for listing roles. +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] +#[serde(rename_all = "lowercase")] +pub enum ListRolesOrder { + /// Ascending order + Asc, + /// Descending order + Desc, +} + +/// Query parameters for listing roles. +#[derive(Debug, Serialize, Default, Clone, Builder, PartialEq)] +#[builder(name = "ListRolesQueryArgs")] +#[builder(pattern = "mutable")] +#[builder(setter(into, strip_option), default)] +#[builder(derive(Debug))] +#[builder(build_fn(error = "OpenAIError"))] +pub struct ListRolesQuery { + /// A limit on the number of roles to return. Defaults to 1000. + #[serde(skip_serializing_if = "Option::is_none")] + pub limit: Option, + /// Cursor for pagination. Provide the value from the previous response's `next` field to continue listing roles. + #[serde(skip_serializing_if = "Option::is_none")] + pub after: Option, + /// Sort order for the returned roles. + #[serde(skip_serializing_if = "Option::is_none")] + pub order: Option, +} + +/// Details about a role that can be assigned through the public Roles API. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct Role { + /// The object type, which is always `role`. + pub object: String, + /// Identifier for the role. + pub id: String, + /// Unique name for the role. + pub name: String, + /// Optional description of the role. + pub description: Option, + /// Permissions granted by the role. + pub permissions: Vec, + /// Resource type the role is bound to (for example `api.organization` or `api.project`). + pub resource_type: String, + /// Whether the role is predefined and managed by OpenAI. + pub predefined_role: bool, +} + +/// Paginated list of roles available on an organization or project. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct PublicRoleListResource { + /// The object type, which is always `list`. + pub object: String, + /// Roles returned in the current page. + pub data: Vec, + /// Whether more roles are available when paginating. + pub has_more: bool, + /// Cursor to fetch the next page of results, or `null` when there are no additional roles. + pub next: Option, +} + +/// Request payload for creating a custom role. +#[derive(Debug, Serialize, Deserialize, Builder, Clone, PartialEq)] +#[builder(name = "CreateOrganizationRoleRequestArgs")] +#[builder(pattern = "mutable")] +#[builder(setter(into, strip_option))] +#[builder(derive(Debug))] +#[builder(build_fn(error = "OpenAIError"))] +pub struct PublicCreateOrganizationRoleBody { + /// Unique name for the role. + pub role_name: String, + /// Permissions to grant to the role. + pub permissions: Vec, + /// Optional description of the role. + #[serde(skip_serializing_if = "Option::is_none")] + pub description: Option, +} + +/// Request payload for updating an existing role. +#[derive(Debug, Serialize, Deserialize, Builder, Clone, PartialEq)] +#[builder(name = "UpdateOrganizationRoleRequestArgs")] +#[builder(pattern = "mutable")] +#[builder(setter(into, strip_option))] +#[builder(derive(Debug))] +#[builder(build_fn(error = "OpenAIError"))] +pub struct PublicUpdateOrganizationRoleBody { + /// Updated set of permissions for the role. + #[serde(skip_serializing_if = "Option::is_none")] + pub permissions: Option>, + /// New description for the role. + #[serde(skip_serializing_if = "Option::is_none")] + pub description: Option, + /// New name for the role. + #[serde(skip_serializing_if = "Option::is_none")] + pub role_name: Option, +} + +/// Confirmation payload returned after deleting a role. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct RoleDeletedResource { + /// The object type, which is always `role.deleted`. + pub object: String, + /// Identifier of the deleted role. + pub id: String, + /// Whether the role was deleted. + pub deleted: bool, +} + +/// Detailed information about a role assignment entry returned when listing assignments. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct AssignedRoleDetails { + /// Identifier for the role. + pub id: String, + /// Name of the role. + pub name: String, + /// Permissions associated with the role. + pub permissions: Vec, + /// Resource type the role applies to. + pub resource_type: String, + /// Whether the role is predefined by OpenAI. + pub predefined_role: bool, + /// Description of the role. + pub description: Option, + /// When the role was created. + pub created_at: Option, + /// When the role was last updated. + pub updated_at: Option, + /// Identifier of the actor who created the role. + pub created_by: Option, + /// User details for the actor that created the role, when available. + #[serde(skip_serializing_if = "Option::is_none")] + pub created_by_user_obj: Option, + /// Arbitrary metadata stored on the role. + #[serde(skip_serializing_if = "Option::is_none")] + pub metadata: Option, +} + +/// Paginated list of roles assigned to a principal. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct RoleListResource { + /// The object type, which is always `list`. + pub object: String, + /// Role assignments returned in the current page. + pub data: Vec, + /// Whether additional assignments are available when paginating. + pub has_more: bool, + /// Cursor to fetch the next page of results, or `null` when there are no more assignments. + pub next: Option, +} + +/// Confirmation payload returned after unassigning a role. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct DeletedRoleAssignmentResource { + /// Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. + pub object: String, + /// Whether the assignment was removed. + pub deleted: bool, +} diff --git a/async-openai/src/types/admin/users.rs b/async-openai/src/types/admin/users.rs index 32e3b1a0..d8d44056 100644 --- a/async-openai/src/types/admin/users.rs +++ b/async-openai/src/types/admin/users.rs @@ -1,3 +1,4 @@ +use crate::types::admin::roles::Role; use crate::types::OpenAIError; use crate::types::OrganizationRole; use derive_builder::Builder; @@ -67,3 +68,39 @@ pub struct UserDeleteResponse { pub id: String, pub deleted: bool, } + +/// Role assignment linking a user to a role. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct UserRoleAssignment { + /// The object type, which is always `user.role`. + pub object: String, + /// The user. + pub user: User, + /// The role. + pub role: Role, +} + +/// Paginated list of role assignments for a user. +#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)] +pub struct UserRoleAssignmentListResource { + /// The object type, which is always `list`. + pub object: String, + /// Role assignments returned in the current page. + pub data: Vec, + /// Whether additional assignments are available when paginating. + pub has_more: bool, + /// Cursor to fetch the next page of results, or `null` when there are no more assignments. + pub next: Option, +} + +/// Request payload for assigning a role to a user. +#[derive(Debug, Serialize, Deserialize, Builder, Clone, PartialEq)] +#[builder(name = "AssignUserRoleRequestArgs")] +#[builder(pattern = "mutable")] +#[builder(setter(into, strip_option))] +#[builder(derive(Debug))] +#[builder(build_fn(error = "OpenAIError"))] +pub struct PublicAssignOrganizationUserRoleBody { + /// Identifier of the role to assign. + pub role_id: String, +} diff --git a/async-openai/src/user_roles.rs b/async-openai/src/user_roles.rs new file mode 100644 index 00000000..6b7f5657 --- /dev/null +++ b/async-openai/src/user_roles.rs @@ -0,0 +1,64 @@ +use crate::{ + config::Config, + error::OpenAIError, + types::admin::roles::{DeletedRoleAssignmentResource, RoleListResource}, + types::admin::users::{PublicAssignOrganizationUserRoleBody, UserRoleAssignment}, + Client, RequestOptions, +}; + +/// Manage role assignments for users in the organization. +pub struct UserRoles<'c, C: Config> { + client: &'c Client, + pub user_id: String, + pub(crate) request_options: RequestOptions, +} + +impl<'c, C: Config> UserRoles<'c, C> { + pub fn new(client: &'c Client, user_id: &str) -> Self { + Self { + client, + user_id: user_id.into(), + request_options: RequestOptions::new(), + } + } + + /// Lists all role assignments for a user. + #[crate::byot(R = serde::de::DeserializeOwned)] + pub async fn list(&self) -> Result { + self.client + .get( + format!("/organization/users/{}/roles", self.user_id).as_str(), + &self.request_options, + ) + .await + } + + /// Assigns a role to a user. + #[crate::byot(T0 = serde::Serialize, R = serde::de::DeserializeOwned)] + pub async fn assign( + &self, + request: PublicAssignOrganizationUserRoleBody, + ) -> Result { + self.client + .post( + format!("/organization/users/{}/roles", self.user_id).as_str(), + request, + &self.request_options, + ) + .await + } + + /// Unassigns a role from a user. + #[crate::byot(T0 = std::fmt::Display, R = serde::de::DeserializeOwned)] + pub async fn unassign( + &self, + role_id: &str, + ) -> Result { + self.client + .delete( + format!("/organization/users/{}/roles/{}", self.user_id, role_id).as_str(), + &self.request_options, + ) + .await + } +} diff --git a/async-openai/src/users.rs b/async-openai/src/users.rs index 66fba4aa..a38f4efd 100644 --- a/async-openai/src/users.rs +++ b/async-openai/src/users.rs @@ -2,6 +2,7 @@ use crate::{ config::Config, error::OpenAIError, types::admin::users::{User, UserDeleteResponse, UserListResponse, UserRoleUpdateRequest}, + user_roles::UserRoles, Client, RequestOptions, }; @@ -19,6 +20,11 @@ impl<'c, C: Config> Users<'c, C> { } } + /// To call [UserRoles] group related APIs using this client. + pub fn roles(&self, user_id: &str) -> UserRoles<'_, C> { + UserRoles::new(self.client, user_id) + } + /// Lists all of the users in the organization. #[crate::byot(R = serde::de::DeserializeOwned)] pub async fn list(&self) -> Result { @@ -59,7 +65,7 @@ impl<'c, C: Config> Users<'c, C> { pub async fn delete(&self, user_id: &str) -> Result { self.client .delete( - format!("/organizations/users/{user_id}").as_str(), + format!("/organization/users/{user_id}").as_str(), &self.request_options, ) .await diff --git a/openapi.documented.yml b/openapi.documented.yml index d0ebd172..e787813f 100644 --- a/openapi.documented.yml +++ b/openapi.documented.yml @@ -14657,6 +14657,564 @@ paths: -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" description: Get costs details for the organization. + /organization/groups: + get: + summary: List groups + operationId: list-groups + tags: + - Groups + parameters: + - name: limit + in: query + description: > + A limit on the number of groups to be returned. Limit can range between 0 and 1000, and the + default is 100. + required: false + schema: + type: integer + minimum: 0 + maximum: 1000 + default: 100 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is a group ID that defines your place in the list. For + instance, if you make a list request and receive 100 objects, ending with group_abc, your + subsequent call can include `after=group_abc` in order to fetch the next page of the list. + required: false + schema: + type: string + - name: order + in: query + description: Specifies the sort order of the returned groups. + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + responses: + '200': + description: Groups listed successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/GroupListResource' + x-oaiMeta: + name: List groups + group: administration + returns: A list of [group objects](https://platform.openai.com/docs/api-reference/groups/object). + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/groups?limit=20&order=asc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "group", + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "is_scim_managed": false + } + ], + "has_more": false, + "next": null + } + description: Lists all groups in the organization. + post: + summary: Create group + operationId: create-group + tags: + - Groups + requestBody: + description: Parameters for the group you want to create. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateGroupBody' + responses: + '200': + description: Group created successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/GroupResponse' + x-oaiMeta: + name: Create group + group: administration + returns: The created [group object](https://platform.openai.com/docs/api-reference/groups/object). + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/groups \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Support Team" + }' + response: | + { + "object": "group", + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "is_scim_managed": false + } + description: Creates a new group in the organization. + /organization/groups/{group_id}: + post: + summary: Update group + operationId: update-group + tags: + - Groups + parameters: + - name: group_id + in: path + description: The ID of the group to update. + required: true + schema: + type: string + requestBody: + description: New attributes to set on the group. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateGroupBody' + responses: + '200': + description: Group updated successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/GroupResourceWithSuccess' + x-oaiMeta: + name: Update group + group: administration + returns: The updated [group object](https://platform.openai.com/docs/api-reference/groups/object). + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Escalations" + }' + response: | + { + "id": "group_01J1F8ABCDXYZ", + "name": "Escalations", + "created_at": 1711471533, + "is_scim_managed": false + } + description: Updates a group's information. + delete: + summary: Delete group + operationId: delete-group + tags: + - Groups + parameters: + - name: group_id + in: path + description: The ID of the group to delete. + required: true + schema: + type: string + responses: + '200': + description: Group deleted successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/GroupDeletedResource' + x-oaiMeta: + name: Delete group + group: administration + returns: Confirmation of the deleted group. + examples: + request: + curl: | + curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "group.deleted", + "id": "group_01J1F8ABCDXYZ", + "deleted": true + } + description: Deletes a group from the organization. + /organization/groups/{group_id}/roles: + get: + summary: List group organization role assignments + operationId: list-group-role-assignments + tags: + - Group organization role assignments + parameters: + - name: group_id + in: path + description: The ID of the group whose organization role assignments you want to list. + required: true + schema: + type: string + - name: limit + in: query + description: A limit on the number of organization role assignments to return. + required: false + schema: + type: integer + minimum: 0 + maximum: 1000 + - name: after + in: query + description: >- + Cursor for pagination. Provide the value from the previous response's `next` field to continue + listing organization roles. + required: false + schema: + type: string + - name: order + in: query + description: Sort order for the returned organization roles. + required: false + schema: + type: string + enum: + - asc + - desc + responses: + '200': + description: Group organization role assignments listed successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/RoleListResource' + x-oaiMeta: + name: List group organization role assignments + group: administration + returns: A list of [role objects](https://platform.openai.com/docs/api-reference/roles/object). + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false, + "description": "Allows managing organization groups", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": { + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com" + }, + "metadata": {} + } + ], + "has_more": false, + "next": null + } + description: Lists the organization roles assigned to a group within the organization. + post: + summary: Assign organization role to group + operationId: assign-group-role + tags: + - Group organization role assignments + parameters: + - name: group_id + in: path + description: The ID of the group that should receive the organization role. + required: true + schema: + type: string + requestBody: + description: Identifies the organization role to assign to the group. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PublicAssignOrganizationGroupRoleBody' + responses: + '200': + description: Organization role assigned to the group successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/GroupRoleAssignment' + x-oaiMeta: + name: Assign organization role to group + group: administration + returns: >- + The created [group role + object](https://platform.openai.com/docs/api-reference/role-assignments/objects/group). + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_id": "role_01J1F8ROLE01" + }' + response: | + { + "object": "group.role", + "group": { + "object": "group", + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "scim_managed": false + }, + "role": { + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false + } + } + description: Assigns an organization role to a group within the organization. + /organization/groups/{group_id}/roles/{role_id}: + delete: + summary: Unassign organization role from group + operationId: unassign-group-role + tags: + - Group organization role assignments + parameters: + - name: group_id + in: path + description: The ID of the group to modify. + required: true + schema: + type: string + - name: role_id + in: path + description: The ID of the organization role to remove from the group. + required: true + schema: + type: string + responses: + '200': + description: Organization role unassigned from the group successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/DeletedRoleAssignmentResource' + x-oaiMeta: + name: Unassign organization role from group + group: administration + returns: >- + Confirmation of the deleted [group role + object](https://platform.openai.com/docs/api-reference/role-assignments/objects/group). + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8ROLE01 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "group.role.deleted", + "deleted": true + } + description: Unassigns an organization role from a group within the organization. + /organization/groups/{group_id}/users: + get: + summary: List group users + operationId: list-group-users + tags: + - Group users + parameters: + - name: group_id + in: path + description: The ID of the group to inspect. + required: true + schema: + type: string + - name: limit + in: query + description: > + A limit on the number of users to be returned. Limit can range between 0 and 1000, and the default + is 100. + required: false + schema: + type: integer + minimum: 0 + maximum: 1000 + default: 100 + - name: after + in: query + description: > + A cursor for use in pagination. Provide the ID of the last user from the previous list response to + retrieve the next page. + required: false + schema: + type: string + - name: order + in: query + description: Specifies the sort order of users in the list. + required: false + schema: + type: string + enum: + - asc + - desc + default: desc + responses: + '200': + description: Group users listed successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/UserListResource' + x-oaiMeta: + name: List group users + group: administration + returns: A list of [user objects](https://platform.openai.com/docs/api-reference/users/object). + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users?limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "organization.user", + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com", + "role": "owner", + "added_at": 1711471533 + } + ], + "has_more": false, + "next": null + } + description: Lists the users assigned to a group. + post: + summary: Add group user + operationId: add-group-user + tags: + - Group users + parameters: + - name: group_id + in: path + description: The ID of the group to update. + required: true + schema: + type: string + requestBody: + description: Identifies the user that should be added to the group. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateGroupUserBody' + responses: + '200': + description: User added to the group successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/GroupUserAssignment' + x-oaiMeta: + name: Add group user + group: administration + returns: >- + The created [group user + object](https://platform.openai.com/docs/api-reference/groups/users/assignment-object). + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "user_id": "user_abc123" + }' + response: | + { + "object": "group.user", + "user_id": "user_abc123", + "group_id": "group_01J1F8ABCDXYZ" + } + description: Adds a user to a group. + /organization/groups/{group_id}/users/{user_id}: + delete: + summary: Remove group user + operationId: remove-group-user + tags: + - Group users + parameters: + - name: group_id + in: path + description: The ID of the group to update. + required: true + schema: + type: string + - name: user_id + in: path + description: The ID of the user to remove from the group. + required: true + schema: + type: string + responses: + '200': + description: User removed from the group successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/GroupUserDeletedResource' + x-oaiMeta: + name: Remove group user + group: administration + returns: >- + Confirmation of the deleted [group user + object](https://platform.openai.com/docs/api-reference/groups/users/assignment-object). + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users/user_abc123 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "group.user.deleted", + "deleted": true + } + description: Removes a user from a group. /organization/invites: get: summary: List invites @@ -15519,6 +16077,175 @@ paths: description: | Deactivate certificates at the project level. You can atomically and idempotently deactivate up to 10 certificates at a time. + /organization/projects/{project_id}/groups: + get: + summary: List project groups + operationId: list-project-groups + tags: + - Project groups + parameters: + - name: project_id + in: path + description: The ID of the project to inspect. + required: true + schema: + type: string + - name: limit + in: query + description: A limit on the number of project groups to return. Defaults to 20. + required: false + schema: + type: integer + minimum: 0 + maximum: 100 + default: 20 + - name: after + in: query + description: >- + Cursor for pagination. Provide the ID of the last group from the previous response to fetch the + next page. + required: false + schema: + type: string + - name: order + in: query + description: Sort order for the returned groups. + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + responses: + '200': + description: Project groups listed successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ProjectGroupListResource' + x-oaiMeta: + name: List project groups + group: administration + returns: >- + A list of [project group + objects](https://platform.openai.com/docs/api-reference/project-groups/object). + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc123/groups?limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "project.group", + "project_id": "proj_abc123", + "group_id": "group_01J1F8ABCDXYZ", + "group_name": "Support Team", + "created_at": 1711471533 + } + ], + "has_more": false, + "next": null + } + description: Lists the groups that have access to a project. + post: + summary: Add project group + operationId: add-project-group + tags: + - Project groups + parameters: + - name: project_id + in: path + description: The ID of the project to update. + required: true + schema: + type: string + requestBody: + description: Identifies the group and role to assign to the project. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/InviteProjectGroupBody' + responses: + '200': + description: Group granted access to the project successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ProjectGroup' + x-oaiMeta: + name: Add project group + group: administration + returns: >- + The created [project group + object](https://platform.openai.com/docs/api-reference/project-groups/object). + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/projects/proj_abc123/groups \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "group_id": "group_01J1F8ABCDXYZ", + "role": "role_01J1F8PROJ" + }' + response: | + { + "object": "project.group", + "project_id": "proj_abc123", + "group_id": "group_01J1F8ABCDXYZ", + "group_name": "Support Team", + "created_at": 1711471533 + } + description: Grants a group access to a project. + /organization/projects/{project_id}/groups/{group_id}: + delete: + summary: Remove project group + operationId: remove-project-group + tags: + - Project groups + parameters: + - name: project_id + in: path + description: The ID of the project to update. + required: true + schema: + type: string + - name: group_id + in: path + description: The ID of the group to remove from the project. + required: true + schema: + type: string + responses: + '200': + description: Group removed from the project successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ProjectGroupDeletedResource' + x-oaiMeta: + name: Remove project group + group: administration + returns: Confirmation of the deleted project group. + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/organization/projects/proj_abc123/groups/group_01J1F8ABCDXYZ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "project.group.deleted", + "deleted": true + } + description: Revokes a group's access to a project. /organization/projects/{project_id}/rate_limits: get: summary: List project rate limits @@ -16201,151 +16928,228 @@ paths: -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" description: Deletes a user from the project. - /organization/usage/audio_speeches: + /organization/roles: get: - summary: Audio speeches - operationId: usage-audio-speeches + summary: List organization roles + operationId: list-roles tags: - - Usage + - Roles parameters: - - name: start_time - in: query - description: Start time (Unix seconds) of the query time range, inclusive. - required: true - schema: - type: integer - - name: end_time + - name: limit in: query - description: End time (Unix seconds) of the query time range, exclusive. + description: A limit on the number of roles to return. Defaults to 1000. required: false schema: type: integer - - name: bucket_width + minimum: 0 + maximum: 1000 + default: 1000 + - name: after in: query description: >- - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to - `1d`. + Cursor for pagination. Provide the value from the previous response's `next` field to continue + listing roles. required: false schema: type: string - enum: - - 1m - - 1h - - 1d - default: 1d - - name: project_ids - in: query - description: Return only usage for these projects. - required: false - schema: - type: array - items: - type: string - - name: user_ids - in: query - description: Return only usage for these users. - required: false - schema: - type: array - items: - type: string - - name: api_key_ids - in: query - description: Return only usage for these API keys. - required: false - schema: - type: array - items: - type: string - - name: models - in: query - description: Return only usage for these models. - required: false - schema: - type: array - items: - type: string - - name: group_by - in: query - description: >- - Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, - `api_key_id`, `model` or any combination of them. - required: false - schema: - type: array - items: - type: string - enum: - - project_id - - user_id - - api_key_id - - model - - name: limit + - name: order in: query - description: | - Specifies the number of buckets to return. - - `bucket_width=1d`: default: 7, max: 31 - - `bucket_width=1h`: default: 24, max: 168 - - `bucket_width=1m`: default: 60, max: 1440 + description: Sort order for the returned roles. required: false - schema: - type: integer - - name: page - in: query - description: A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. schema: type: string + enum: + - asc + - desc + default: asc responses: '200': - description: Usage data retrieved successfully. + description: Roles listed successfully. content: application/json: schema: - $ref: '#/components/schemas/UsageResponse' + $ref: '#/components/schemas/PublicRoleListResource' x-oaiMeta: - name: Audio speeches - group: usage-audio-speeches - returns: >- - A list of paginated, time bucketed [Audio speeches - usage](https://platform.openai.com/docs/api-reference/usage/audio_speeches_object) objects. + name: List organization roles + group: administration + returns: A list of [role objects](https://platform.openai.com/docs/api-reference/roles/object). examples: + request: + curl: | + curl https://api.openai.com/v1/organization/roles?limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" response: | { - "object": "page", + "object": "list", "data": [ { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.usage.audio_speeches.result", - "characters": 45, - "num_model_requests": 1, - "project_id": null, - "user_id": null, - "api_key_id": null, - "model": null - } - ] + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false } ], "has_more": false, - "next_page": null + "next": null } + description: Lists the roles configured for the organization. + post: + summary: Create organization role + operationId: create-role + tags: + - Roles + requestBody: + description: Parameters for the role you want to create. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PublicCreateOrganizationRoleBody' + responses: + '200': + description: Role created successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/Role' + x-oaiMeta: + name: Create organization role + group: administration + returns: The created [role object](https://platform.openai.com/docs/api-reference/roles/object). + examples: request: - curl: > - curl "https://api.openai.com/v1/organization/usage/audio_speeches?start_time=1730419200&limit=1" - \ - - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - - -H "Content-Type: application/json" - description: Get audio speeches usage details for the organization. - /organization/usage/audio_transcriptions: + curl: | + curl -X POST https://api.openai.com/v1/organization/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "description": "Allows managing organization groups" + }' + response: | + { + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false + } + description: Creates a custom role for the organization. + /organization/roles/{role_id}: + post: + summary: Update organization role + operationId: update-role + tags: + - Roles + parameters: + - name: role_id + in: path + description: The ID of the role to update. + required: true + schema: + type: string + requestBody: + description: Fields to update on the role. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PublicUpdateOrganizationRoleBody' + responses: + '200': + description: Role updated successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/Role' + x-oaiMeta: + name: Update organization role + group: administration + returns: The updated [role object](https://platform.openai.com/docs/api-reference/roles/object). + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "description": "Allows managing organization groups" + }' + response: | + { + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false + } + description: Updates an existing organization role. + delete: + summary: Delete organization role + operationId: delete-role + tags: + - Roles + parameters: + - name: role_id + in: path + description: The ID of the role to delete. + required: true + schema: + type: string + responses: + '200': + description: Role deleted successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/RoleDeletedResource' + x-oaiMeta: + name: Delete organization role + group: administration + returns: Confirmation of the deleted role. + examples: + request: + curl: | + curl -X DELETE https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "role.deleted", + "id": "role_01J1F8ROLE01", + "deleted": true + } + description: Deletes a custom role from the organization. + /organization/usage/audio_speeches: get: - summary: Audio transcriptions - operationId: usage-audio-transcriptions + summary: Audio speeches + operationId: usage-audio-speeches tags: - Usage parameters: @@ -16444,11 +17248,11 @@ paths: schema: $ref: '#/components/schemas/UsageResponse' x-oaiMeta: - name: Audio transcriptions - group: usage-audio-transcriptions + name: Audio speeches + group: usage-audio-speeches returns: >- - A list of paginated, time bucketed [Audio transcriptions - usage](https://platform.openai.com/docs/api-reference/usage/audio_transcriptions_object) objects. + A list of paginated, time bucketed [Audio speeches + usage](https://platform.openai.com/docs/api-reference/usage/audio_speeches_object) objects. examples: response: | { @@ -16460,8 +17264,8 @@ paths: "end_time": 1730505600, "results": [ { - "object": "organization.usage.audio_transcriptions.result", - "seconds": 20, + "object": "organization.usage.audio_speeches.result", + "characters": 45, "num_model_requests": 1, "project_id": null, "user_id": null, @@ -16476,18 +17280,17 @@ paths: } request: curl: > - curl - "https://api.openai.com/v1/organization/usage/audio_transcriptions?start_time=1730419200&limit=1" + curl "https://api.openai.com/v1/organization/usage/audio_speeches?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" - description: Get audio transcriptions usage details for the organization. - /organization/usage/code_interpreter_sessions: + description: Get audio speeches usage details for the organization. + /organization/usage/audio_transcriptions: get: - summary: Code interpreter sessions - operationId: usage-code-interpreter-sessions + summary: Audio transcriptions + operationId: usage-audio-transcriptions tags: - Usage parameters: @@ -16524,9 +17327,35 @@ paths: type: array items: type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string - name: group_by in: query - description: Group the usage data by the specified fields. Support fields include `project_id`. + description: >- + Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, + `api_key_id`, `model` or any combination of them. required: false schema: type: array @@ -16534,6 +17363,9 @@ paths: type: string enum: - project_id + - user_id + - api_key_id + - model - name: limit in: query description: | @@ -16557,12 +17389,11 @@ paths: schema: $ref: '#/components/schemas/UsageResponse' x-oaiMeta: - name: Code interpreter sessions - group: usage-code-interpreter-sessions + name: Audio transcriptions + group: usage-audio-transcriptions returns: >- - A list of paginated, time bucketed [Code interpreter sessions - usage](https://platform.openai.com/docs/api-reference/usage/code_interpreter_sessions_object) - objects. + A list of paginated, time bucketed [Audio transcriptions + usage](https://platform.openai.com/docs/api-reference/usage/audio_transcriptions_object) objects. examples: response: | { @@ -16574,9 +17405,13 @@ paths: "end_time": 1730505600, "results": [ { - "object": "organization.usage.code_interpreter_sessions.result", - "num_sessions": 1, - "project_id": null + "object": "organization.usage.audio_transcriptions.result", + "seconds": 20, + "num_model_requests": 1, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null } ] } @@ -16587,17 +17422,17 @@ paths: request: curl: > curl - "https://api.openai.com/v1/organization/usage/code_interpreter_sessions?start_time=1730419200&limit=1" + "https://api.openai.com/v1/organization/usage/audio_transcriptions?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" - description: Get code interpreter sessions usage details for the organization. - /organization/usage/completions: + description: Get audio transcriptions usage details for the organization. + /organization/usage/code_interpreter_sessions: get: - summary: Completions - operationId: usage-completions + summary: Code interpreter sessions + operationId: usage-code-interpreter-sessions tags: - Usage parameters: @@ -16634,43 +17469,9 @@ paths: type: array items: type: string - - name: user_ids - in: query - description: Return only usage for these users. - required: false - schema: - type: array - items: - type: string - - name: api_key_ids - in: query - description: Return only usage for these API keys. - required: false - schema: - type: array - items: - type: string - - name: models - in: query - description: Return only usage for these models. - required: false - schema: - type: array - items: - type: string - - name: batch - in: query - description: > - If `true`, return batch jobs only. If `false`, return non-batch jobs only. By default, return - both. - required: false - schema: - type: boolean - name: group_by in: query - description: >- - Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, - `api_key_id`, `model`, `batch`, `service_tier` or any combination of them. + description: Group the usage data by the specified fields. Support fields include `project_id`. required: false schema: type: array @@ -16678,11 +17479,6 @@ paths: type: string enum: - project_id - - user_id - - api_key_id - - model - - batch - - service_tier - name: limit in: query description: | @@ -16706,11 +17502,12 @@ paths: schema: $ref: '#/components/schemas/UsageResponse' x-oaiMeta: - name: Completions - group: usage-completions + name: Code interpreter sessions + group: usage-code-interpreter-sessions returns: >- - A list of paginated, time bucketed [Completions - usage](https://platform.openai.com/docs/api-reference/usage/completions_object) objects. + A list of paginated, time bucketed [Code interpreter sessions + usage](https://platform.openai.com/docs/api-reference/usage/code_interpreter_sessions_object) + objects. examples: response: | { @@ -16722,36 +17519,30 @@ paths: "end_time": 1730505600, "results": [ { - "object": "organization.usage.completions.result", - "input_tokens": 1000, - "output_tokens": 500, - "input_cached_tokens": 800, - "input_audio_tokens": 0, - "output_audio_tokens": 0, - "num_model_requests": 5, - "project_id": null, - "user_id": null, - "api_key_id": null, - "model": null, - "batch": null, - "service_tier": null + "object": "organization.usage.code_interpreter_sessions.result", + "num_sessions": 1, + "project_id": null } ] } ], - "has_more": true, - "next_page": "page_AAAAAGdGxdEiJdKOAAAAAGcqsYA=" + "has_more": false, + "next_page": null } request: - curl: | - curl "https://api.openai.com/v1/organization/usage/completions?start_time=1730419200&limit=1" \ + curl: > + curl + "https://api.openai.com/v1/organization/usage/code_interpreter_sessions?start_time=1730419200&limit=1" + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" - description: Get completions usage details for the organization. - /organization/usage/embeddings: + description: Get code interpreter sessions usage details for the organization. + /organization/usage/completions: get: - summary: Embeddings - operationId: usage-embeddings + summary: Completions + operationId: usage-completions tags: - Usage parameters: @@ -16812,11 +17603,19 @@ paths: type: array items: type: string + - name: batch + in: query + description: > + If `true`, return batch jobs only. If `false`, return non-batch jobs only. By default, return + both. + required: false + schema: + type: boolean - name: group_by in: query description: >- Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, - `api_key_id`, `model` or any combination of them. + `api_key_id`, `model`, `batch`, `service_tier` or any combination of them. required: false schema: type: array @@ -16827,6 +17626,8 @@ paths: - user_id - api_key_id - model + - batch + - service_tier - name: limit in: query description: | @@ -16850,11 +17651,11 @@ paths: schema: $ref: '#/components/schemas/UsageResponse' x-oaiMeta: - name: Embeddings - group: usage-embeddings + name: Completions + group: usage-completions returns: >- - A list of paginated, time bucketed [Embeddings - usage](https://platform.openai.com/docs/api-reference/usage/embeddings_object) objects. + A list of paginated, time bucketed [Completions + usage](https://platform.openai.com/docs/api-reference/usage/completions_object) objects. examples: response: | { @@ -16866,30 +17667,36 @@ paths: "end_time": 1730505600, "results": [ { - "object": "organization.usage.embeddings.result", - "input_tokens": 16, - "num_model_requests": 2, + "object": "organization.usage.completions.result", + "input_tokens": 1000, + "output_tokens": 500, + "input_cached_tokens": 800, + "input_audio_tokens": 0, + "output_audio_tokens": 0, + "num_model_requests": 5, "project_id": null, "user_id": null, "api_key_id": null, - "model": null + "model": null, + "batch": null, + "service_tier": null } ] } ], - "has_more": false, - "next_page": null + "has_more": true, + "next_page": "page_AAAAAGdGxdEiJdKOAAAAAGcqsYA=" } request: curl: | - curl "https://api.openai.com/v1/organization/usage/embeddings?start_time=1730419200&limit=1" \ + curl "https://api.openai.com/v1/organization/usage/completions?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" - description: Get embeddings usage details for the organization. - /organization/usage/images: + description: Get completions usage details for the organization. + /organization/usage/embeddings: get: - summary: Images - operationId: usage-images + summary: Embeddings + operationId: usage-embeddings tags: - Usage parameters: @@ -16918,36 +17725,6 @@ paths: - 1h - 1d default: 1d - - name: sources - in: query - description: >- - Return only usages for these sources. Possible values are `image.generation`, `image.edit`, - `image.variation` or any combination of them. - required: false - schema: - type: array - items: - type: string - enum: - - image.generation - - image.edit - - image.variation - - name: sizes - in: query - description: >- - Return only usages for these image sizes. Possible values are `256x256`, `512x512`, `1024x1024`, - `1792x1792`, `1024x1792` or any combination of them. - required: false - schema: - type: array - items: - type: string - enum: - - 256x256 - - 512x512 - - 1024x1024 - - 1792x1792 - - 1024x1792 - name: project_ids in: query description: Return only usage for these projects. @@ -16984,7 +17761,7 @@ paths: in: query description: >- Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, - `api_key_id`, `model`, `size`, `source` or any combination of them. + `api_key_id`, `model` or any combination of them. required: false schema: type: array @@ -16995,8 +17772,6 @@ paths: - user_id - api_key_id - model - - size - - source - name: limit in: query description: | @@ -17020,11 +17795,11 @@ paths: schema: $ref: '#/components/schemas/UsageResponse' x-oaiMeta: - name: Images - group: usage-images + name: Embeddings + group: usage-embeddings returns: >- - A list of paginated, time bucketed [Images - usage](https://platform.openai.com/docs/api-reference/usage/images_object) objects. + A list of paginated, time bucketed [Embeddings + usage](https://platform.openai.com/docs/api-reference/usage/embeddings_object) objects. examples: response: | { @@ -17036,11 +17811,9 @@ paths: "end_time": 1730505600, "results": [ { - "object": "organization.usage.images.result", - "images": 2, + "object": "organization.usage.embeddings.result", + "input_tokens": 16, "num_model_requests": 2, - "size": null, - "source": null, "project_id": null, "user_id": null, "api_key_id": null, @@ -17054,14 +17827,186 @@ paths: } request: curl: | - curl "https://api.openai.com/v1/organization/usage/images?start_time=1730419200&limit=1" \ + curl "https://api.openai.com/v1/organization/usage/embeddings?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" - description: Get images usage details for the organization. - /organization/usage/moderations: + description: Get embeddings usage details for the organization. + /organization/usage/images: get: - summary: Moderations - operationId: usage-moderations + summary: Images + operationId: usage-images + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: >- + Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to + `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: sources + in: query + description: >- + Return only usages for these sources. Possible values are `image.generation`, `image.edit`, + `image.variation` or any combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - image.generation + - image.edit + - image.variation + - name: sizes + in: query + description: >- + Return only usages for these image sizes. Possible values are `256x256`, `512x512`, `1024x1024`, + `1792x1792`, `1024x1792` or any combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - 256x256 + - 512x512 + - 1024x1024 + - 1792x1792 + - 1024x1792 + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: >- + Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, + `api_key_id`, `model`, `size`, `source` or any combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - size + - source + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. + schema: + type: string + responses: + '200': + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/UsageResponse' + x-oaiMeta: + name: Images + group: usage-images + returns: >- + A list of paginated, time bucketed [Images + usage](https://platform.openai.com/docs/api-reference/usage/images_object) objects. + examples: + response: | + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.images.result", + "images": 2, + "num_model_requests": 2, + "size": null, + "source": null, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + request: + curl: | + curl "https://api.openai.com/v1/organization/usage/images?start_time=1730419200&limit=1" \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + description: Get images usage details for the organization. + /organization/usage/moderations: + get: + summary: Moderations + operationId: usage-moderations tags: - Usage parameters: @@ -17499,6 +18444,872 @@ paths: -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" description: Deletes a user from the organization. + /organization/users/{user_id}/roles: + get: + summary: List user organization role assignments + operationId: list-user-role-assignments + tags: + - User organization role assignments + parameters: + - name: user_id + in: path + description: The ID of the user to inspect. + required: true + schema: + type: string + - name: limit + in: query + description: A limit on the number of organization role assignments to return. + required: false + schema: + type: integer + minimum: 0 + maximum: 1000 + - name: after + in: query + description: >- + Cursor for pagination. Provide the value from the previous response's `next` field to continue + listing organization roles. + required: false + schema: + type: string + - name: order + in: query + description: Sort order for the returned organization roles. + required: false + schema: + type: string + enum: + - asc + - desc + responses: + '200': + description: User organization role assignments listed successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/RoleListResource' + x-oaiMeta: + name: List user organization role assignments + group: administration + returns: A list of [role objects](https://platform.openai.com/docs/api-reference/roles/object). + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/users/user_abc123/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false, + "description": "Allows managing organization groups", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": { + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com" + }, + "metadata": {} + } + ], + "has_more": false, + "next": null + } + description: Lists the organization roles assigned to a user within the organization. + post: + summary: Assign organization role to user + operationId: assign-user-role + tags: + - User organization role assignments + parameters: + - name: user_id + in: path + description: The ID of the user that should receive the organization role. + required: true + schema: + type: string + requestBody: + description: Identifies the organization role to assign to the user. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PublicAssignOrganizationGroupRoleBody' + responses: + '200': + description: Organization role assigned to the user successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/UserRoleAssignment' + x-oaiMeta: + name: Assign organization role to user + group: administration + returns: >- + The created [user role + object](https://platform.openai.com/docs/api-reference/role-assignments/objects/user). + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/users/user_abc123/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_id": "role_01J1F8ROLE01" + }' + response: | + { + "object": "user.role", + "user": { + "object": "organization.user", + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com", + "role": "owner", + "added_at": 1711470000 + }, + "role": { + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false + } + } + description: Assigns an organization role to a user within the organization. + /organization/users/{user_id}/roles/{role_id}: + delete: + summary: Unassign organization role from user + operationId: unassign-user-role + tags: + - User organization role assignments + parameters: + - name: user_id + in: path + description: The ID of the user to modify. + required: true + schema: + type: string + - name: role_id + in: path + description: The ID of the organization role to remove from the user. + required: true + schema: + type: string + responses: + '200': + description: Organization role unassigned from the user successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/DeletedRoleAssignmentResource' + x-oaiMeta: + name: Unassign organization role from user + group: administration + returns: >- + Confirmation of the deleted [user role + object](https://platform.openai.com/docs/api-reference/role-assignments/objects/user). + examples: + request: + curl: > + curl -X DELETE https://api.openai.com/v1/organization/users/user_abc123/roles/role_01J1F8ROLE01 + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "user.role.deleted", + "deleted": true + } + description: Unassigns an organization role from a user within the organization. + /projects/{project_id}/groups/{group_id}/roles: + get: + summary: List project group role assignments + operationId: list-project-group-role-assignments + tags: + - Project group role assignments + parameters: + - name: project_id + in: path + description: The ID of the project to inspect. + required: true + schema: + type: string + - name: group_id + in: path + description: The ID of the group to inspect. + required: true + schema: + type: string + - name: limit + in: query + description: A limit on the number of project role assignments to return. + required: false + schema: + type: integer + minimum: 0 + maximum: 1000 + - name: after + in: query + description: >- + Cursor for pagination. Provide the value from the previous response's `next` field to continue + listing project roles. + required: false + schema: + type: string + - name: order + in: query + description: Sort order for the returned project roles. + required: false + schema: + type: string + enum: + - asc + - desc + responses: + '200': + description: Project group role assignments listed successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/RoleListResource' + x-oaiMeta: + name: List project group role assignments + group: administration + returns: A list of [role objects](https://platform.openai.com/docs/api-reference/roles/object). + examples: + request: + curl: | + curl https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false, + "description": "Allows managing API keys for the project", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": { + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com" + }, + "metadata": {} + } + ], + "has_more": false, + "next": null + } + description: Lists the project roles assigned to a group within a project. + post: + summary: Assign project role to group + operationId: assign-project-group-role + tags: + - Project group role assignments + parameters: + - name: project_id + in: path + description: The ID of the project to update. + required: true + schema: + type: string + - name: group_id + in: path + description: The ID of the group that should receive the project role. + required: true + schema: + type: string + requestBody: + description: Identifies the project role to assign to the group. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PublicAssignOrganizationGroupRoleBody' + responses: + '200': + description: Project role assigned to the group successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/GroupRoleAssignment' + x-oaiMeta: + name: Assign project role to group + group: administration + returns: >- + The created [group role + object](https://platform.openai.com/docs/api-reference/role-assignments/objects/group). + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_id": "role_01J1F8PROJ" + }' + response: | + { + "object": "group.role", + "group": { + "object": "group", + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "scim_managed": false + }, + "role": { + "object": "role", + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "description": "Allows managing API keys for the project", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false + } + } + description: Assigns a project role to a group within a project. + /projects/{project_id}/groups/{group_id}/roles/{role_id}: + delete: + summary: Unassign project role from group + operationId: unassign-project-group-role + tags: + - Project group role assignments + parameters: + - name: project_id + in: path + description: The ID of the project to modify. + required: true + schema: + type: string + - name: group_id + in: path + description: The ID of the group whose project role assignment should be removed. + required: true + schema: + type: string + - name: role_id + in: path + description: The ID of the project role to remove from the group. + required: true + schema: + type: string + responses: + '200': + description: Project role unassigned from the group successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/DeletedRoleAssignmentResource' + x-oaiMeta: + name: Unassign project role from group + group: administration + returns: >- + Confirmation of the deleted [group role + object](https://platform.openai.com/docs/api-reference/role-assignments/objects/group). + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8PROJ + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "group.role.deleted", + "deleted": true + } + description: Unassigns a project role from a group within a project. + /projects/{project_id}/roles: + get: + summary: List project roles + operationId: list-project-roles + tags: + - Roles + parameters: + - name: project_id + in: path + description: The ID of the project to inspect. + required: true + schema: + type: string + - name: limit + in: query + description: A limit on the number of roles to return. Defaults to 1000. + required: false + schema: + type: integer + minimum: 0 + maximum: 1000 + default: 1000 + - name: after + in: query + description: >- + Cursor for pagination. Provide the value from the previous response's `next` field to continue + listing roles. + required: false + schema: + type: string + - name: order + in: query + description: Sort order for the returned roles. + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + responses: + '200': + description: Project roles listed successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/PublicRoleListResource' + x-oaiMeta: + name: List project roles + group: administration + returns: >- + A list of [role objects](https://platform.openai.com/docs/api-reference/roles/object) configured on + the project. + examples: + request: + curl: | + curl https://api.openai.com/v1/projects/proj_abc123/roles?limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "object": "role", + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "description": "Allows managing API keys for the project", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false + } + ], + "has_more": false, + "next": null + } + description: Lists the roles configured for a project. + post: + summary: Create project role + operationId: create-project-role + tags: + - Roles + parameters: + - name: project_id + in: path + description: The ID of the project to update. + required: true + schema: + type: string + requestBody: + description: Parameters for the project role you want to create. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PublicCreateOrganizationRoleBody' + responses: + '200': + description: Project role created successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/Role' + x-oaiMeta: + name: Create project role + group: administration + returns: The created [role object](https://platform.openai.com/docs/api-reference/roles/object). + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_name": "API Project Key Manager", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "description": "Allows managing API keys for the project" + }' + response: | + { + "object": "role", + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "description": "Allows managing API keys for the project", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false + } + description: Creates a custom role for a project. + /projects/{project_id}/roles/{role_id}: + post: + summary: Update project role + operationId: update-project-role + tags: + - Roles + parameters: + - name: project_id + in: path + description: The ID of the project to update. + required: true + schema: + type: string + - name: role_id + in: path + description: The ID of the role to update. + required: true + schema: + type: string + requestBody: + description: Fields to update on the project role. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PublicUpdateOrganizationRoleBody' + responses: + '200': + description: Project role updated successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/Role' + x-oaiMeta: + name: Update project role + group: administration + returns: The updated [role object](https://platform.openai.com/docs/api-reference/roles/object). + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_name": "API Project Key Manager", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "description": "Allows managing API keys for the project" + }' + response: | + { + "object": "role", + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "description": "Allows managing API keys for the project", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false + } + description: Updates an existing project role. + delete: + summary: Delete project role + operationId: delete-project-role + tags: + - Roles + parameters: + - name: project_id + in: path + description: The ID of the project to update. + required: true + schema: + type: string + - name: role_id + in: path + description: The ID of the role to delete. + required: true + schema: + type: string + responses: + '200': + description: Project role deleted successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/RoleDeletedResource' + x-oaiMeta: + name: Delete project role + group: administration + returns: Confirmation of the deleted role. + examples: + request: + curl: | + curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "role.deleted", + "id": "role_01J1F8PROJ", + "deleted": true + } + description: Deletes a custom role from a project. + /projects/{project_id}/users/{user_id}/roles: + get: + summary: List project user role assignments + operationId: list-project-user-role-assignments + tags: + - Project user role assignments + parameters: + - name: project_id + in: path + description: The ID of the project to inspect. + required: true + schema: + type: string + - name: user_id + in: path + description: The ID of the user to inspect. + required: true + schema: + type: string + - name: limit + in: query + description: A limit on the number of project role assignments to return. + required: false + schema: + type: integer + minimum: 0 + maximum: 1000 + - name: after + in: query + description: >- + Cursor for pagination. Provide the value from the previous response's `next` field to continue + listing project roles. + required: false + schema: + type: string + - name: order + in: query + description: Sort order for the returned project roles. + required: false + schema: + type: string + enum: + - asc + - desc + responses: + '200': + description: Project user role assignments listed successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/RoleListResource' + x-oaiMeta: + name: List project user role assignments + group: administration + returns: A list of [role objects](https://platform.openai.com/docs/api-reference/roles/object). + examples: + request: + curl: | + curl https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "list", + "data": [ + { + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false, + "description": "Allows managing API keys for the project", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": { + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com" + }, + "metadata": {} + } + ], + "has_more": false, + "next": null + } + description: Lists the project roles assigned to a user within a project. + post: + summary: Assign project role to user + operationId: assign-project-user-role + tags: + - Project user role assignments + parameters: + - name: project_id + in: path + description: The ID of the project to update. + required: true + schema: + type: string + - name: user_id + in: path + description: The ID of the user that should receive the project role. + required: true + schema: + type: string + requestBody: + description: Identifies the project role to assign to the user. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PublicAssignOrganizationGroupRoleBody' + responses: + '200': + description: Project role assigned to the user successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/UserRoleAssignment' + x-oaiMeta: + name: Assign project role to user + group: administration + returns: >- + The created [user role + object](https://platform.openai.com/docs/api-reference/role-assignments/objects/user). + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_id": "role_01J1F8PROJ" + }' + response: | + { + "object": "user.role", + "user": { + "object": "organization.user", + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com", + "role": "owner", + "added_at": 1711470000 + }, + "role": { + "object": "role", + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "description": "Allows managing API keys for the project", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false + } + } + description: Assigns a project role to a user within a project. + /projects/{project_id}/users/{user_id}/roles/{role_id}: + delete: + summary: Unassign project role from user + operationId: unassign-project-user-role + tags: + - Project user role assignments + parameters: + - name: project_id + in: path + description: The ID of the project to modify. + required: true + schema: + type: string + - name: user_id + in: path + description: The ID of the user whose project role assignment should be removed. + required: true + schema: + type: string + - name: role_id + in: path + description: The ID of the project role to remove from the user. + required: true + schema: + type: string + responses: + '200': + description: Project role unassigned from the user successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/DeletedRoleAssignmentResource' + x-oaiMeta: + name: Unassign project role from user + group: administration + returns: >- + Confirmation of the deleted [user role + object](https://platform.openai.com/docs/api-reference/role-assignments/objects/user). + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles/role_01J1F8PROJ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "user.role.deleted", + "deleted": true + } + description: Unassigns a project role from a user within a project. /realtime/calls: post: summary: Create call @@ -30014,6 +31825,73 @@ components: last_id: type: string example: key_xyz + AssignedRoleDetails: + type: object + description: Detailed information about a role assignment entry returned when listing assignments. + properties: + id: + type: string + description: Identifier for the role. + name: + type: string + description: Name of the role. + permissions: + type: array + description: Permissions associated with the role. + items: + type: string + resource_type: + type: string + description: Resource type the role applies to. + predefined_role: + type: boolean + description: Whether the role is predefined by OpenAI. + description: + description: Description of the role. + anyOf: + - type: string + - type: 'null' + created_at: + description: When the role was created. + anyOf: + - type: integer + format: int64 + - type: 'null' + updated_at: + description: When the role was last updated. + anyOf: + - type: integer + format: int64 + - type: 'null' + created_by: + description: Identifier of the actor who created the role. + anyOf: + - type: string + - type: 'null' + created_by_user_obj: + description: User details for the actor that created the role, when available. + anyOf: + - type: object + additionalProperties: true + - type: 'null' + metadata: + description: Arbitrary metadata stored on the role. + anyOf: + - type: object + additionalProperties: true + - type: 'null' + required: + - id + - name + - permissions + - resource_type + - predefined_role + - description + - created_at + - updated_at + - created_by + - created_by_user_obj + - metadata AssistantObject: type: object title: Assistant @@ -35590,6 +37468,36 @@ components: required: - model - training_file + CreateGroupBody: + type: object + description: Request payload for creating a new group in the organization. + properties: + name: + type: string + description: Human readable name for the group. + minLength: 1 + maxLength: 255 + required: + - name + x-oaiMeta: + example: | + { + "name": "Support Team" + } + CreateGroupUserBody: + type: object + description: Request payload for adding a user to a group. + properties: + user_id: + type: string + description: Identifier of the user to add to the group. + required: + - user_id + x-oaiMeta: + example: | + { + "user_id": "user_abc123" + } CreateImageEditRequest: type: object properties: @@ -37858,6 +39766,26 @@ components: x-oaiMeta: name: The deleted conversation object group: conversations + DeletedRoleAssignmentResource: + type: object + description: Confirmation payload returned after unassigning a role. + properties: + object: + type: string + description: Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. + deleted: + type: boolean + description: Whether the assignment was removed. + required: + - object + - deleted + x-oaiMeta: + name: Role assignment deletion confirmation + example: | + { + "object": "group.role.deleted", + "deleted": true + } DoneEvent: type: object properties: @@ -40993,6 +42921,277 @@ components: "reference": "{{item.label}}", "evaluation_metric": "fuzzy_match" } + Group: + type: object + description: Summary information about a group returned in role assignment responses. + properties: + object: + type: string + enum: + - group + description: Always `group`. + x-stainless-const: true + id: + type: string + description: Identifier for the group. + name: + type: string + description: Display name of the group. + created_at: + type: integer + format: int64 + description: Unix timestamp (in seconds) when the group was created. + scim_managed: + type: boolean + description: Whether the group is managed through SCIM. + required: + - object + - id + - name + - created_at + - scim_managed + x-oaiMeta: + name: The group object + example: | + { + "object": "group", + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "scim_managed": false + } + GroupDeletedResource: + type: object + description: Confirmation payload returned after deleting a group. + properties: + object: + type: string + enum: + - group.deleted + description: Always `group.deleted`. + x-stainless-const: true + id: + type: string + description: Identifier of the deleted group. + deleted: + type: boolean + description: Whether the group was deleted. + required: + - object + - id + - deleted + x-oaiMeta: + example: | + { + "object": "group.deleted", + "id": "group_01J1F8ABCDXYZ", + "deleted": true + } + GroupListResource: + type: object + description: Paginated list of organization groups. + properties: + object: + type: string + enum: + - list + description: Always `list`. + x-stainless-const: true + data: + type: array + description: Groups returned in the current page. + items: + $ref: '#/components/schemas/GroupResponse' + has_more: + type: boolean + description: Whether additional groups are available when paginating. + next: + description: Cursor to fetch the next page of results, or `null` if there are no more results. + anyOf: + - type: string + - type: 'null' + required: + - object + - data + - has_more + - next + x-oaiMeta: + name: Group list + example: | + { + "object": "list", + "data": [ + { + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "is_scim_managed": false + }, + { + "id": "group_01J1F8PQRMNO", + "name": "Sales", + "created_at": 1711472599, + "is_scim_managed": true + } + ], + "has_more": false, + "next": null + } + GroupResourceWithSuccess: + type: object + description: Response returned after updating a group. + properties: + id: + type: string + description: Identifier for the group. + name: + type: string + description: Updated display name for the group. + created_at: + type: integer + format: int64 + description: Unix timestamp (in seconds) when the group was created. + is_scim_managed: + type: boolean + description: Whether the group is managed through SCIM and controlled by your identity provider. + required: + - id + - name + - created_at + - is_scim_managed + x-oaiMeta: + example: | + { + "id": "group_01J1F8ABCDXYZ", + "name": "Escalations", + "created_at": 1711471533, + "is_scim_managed": false + } + GroupResponse: + type: object + description: Details about an organization group. + properties: + id: + type: string + description: Identifier for the group. + name: + type: string + description: Display name of the group. + created_at: + type: integer + format: int64 + description: Unix timestamp (in seconds) when the group was created. + is_scim_managed: + type: boolean + description: Whether the group is managed through SCIM and controlled by your identity provider. + required: + - id + - name + - created_at + - is_scim_managed + x-oaiMeta: + name: Group + example: | + { + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "is_scim_managed": false + } + GroupRoleAssignment: + type: object + description: Role assignment linking a group to a role. + properties: + object: + type: string + enum: + - group.role + description: Always `group.role`. + x-stainless-const: true + group: + $ref: '#/components/schemas/Group' + role: + $ref: '#/components/schemas/Role' + required: + - object + - group + - role + x-oaiMeta: + name: The group role object + example: | + { + "object": "group.role", + "group": { + "object": "group", + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "scim_managed": false + }, + "role": { + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false + } + } + GroupUserAssignment: + type: object + description: Confirmation payload returned after adding a user to a group. + properties: + object: + type: string + enum: + - group.user + description: Always `group.user`. + x-stainless-const: true + user_id: + type: string + description: Identifier of the user that was added. + group_id: + type: string + description: Identifier of the group the user was added to. + required: + - object + - user_id + - group_id + x-oaiMeta: + name: The group user object + example: | + { + "object": "group.user", + "user_id": "user_abc123", + "group_id": "group_01J1F8ABCDXYZ" + } + GroupUserDeletedResource: + type: object + description: Confirmation payload returned after removing a user from a group. + properties: + object: + type: string + enum: + - group.user.deleted + description: Always `group.user.deleted`. + x-stainless-const: true + deleted: + type: boolean + description: Whether the group membership was removed. + required: + - object + - deleted + x-oaiMeta: + name: Group user deletion confirmation + example: | + { + "object": "group.user.deleted", + "deleted": true + } Image: type: object description: Represents the content or the URL of an image generated by the OpenAI API. @@ -41859,6 +44058,25 @@ components: required: - object - data + InviteProjectGroupBody: + type: object + description: Request payload for granting a group access to a project. + properties: + group_id: + type: string + description: Identifier of the group to add to the project. + role: + type: string + description: Identifier of the project role to grant to the group. + required: + - group_id + - role + x-oaiMeta: + example: | + { + "group_id": "group_01J1F8ABCDXYZ", + "role": "role_01J1F8PROJ" + } InviteRequest: type: object properties: @@ -44295,6 +46513,113 @@ components: functionality and limitations of setting this field. required: - name + ProjectGroup: + type: object + description: Details about a group's membership in a project. + properties: + object: + type: string + enum: + - project.group + description: Always `project.group`. + x-stainless-const: true + project_id: + type: string + description: Identifier of the project. + group_id: + type: string + description: Identifier of the group that has access to the project. + group_name: + type: string + description: Display name of the group. + created_at: + type: integer + format: int64 + description: Unix timestamp (in seconds) when the group was granted project access. + required: + - object + - project_id + - group_id + - group_name + - created_at + x-oaiMeta: + name: The project group object + example: | + { + "object": "project.group", + "project_id": "proj_abc123", + "group_id": "group_01J1F8ABCDXYZ", + "group_name": "Support Team", + "created_at": 1711471533 + } + ProjectGroupDeletedResource: + type: object + description: Confirmation payload returned after removing a group from a project. + properties: + object: + type: string + enum: + - project.group.deleted + description: Always `project.group.deleted`. + x-stainless-const: true + deleted: + type: boolean + description: Whether the group membership in the project was removed. + required: + - object + - deleted + x-oaiMeta: + name: Project group deletion confirmation + example: | + { + "object": "project.group.deleted", + "deleted": true + } + ProjectGroupListResource: + type: object + description: Paginated list of groups that have access to a project. + properties: + object: + type: string + enum: + - list + description: Always `list`. + x-stainless-const: true + data: + type: array + description: Project group memberships returned in the current page. + items: + $ref: '#/components/schemas/ProjectGroup' + has_more: + type: boolean + description: Whether additional project group memberships are available. + next: + description: Cursor to fetch the next page of results, or `null` when there are no more results. + anyOf: + - type: string + - type: 'null' + required: + - object + - data + - has_more + - next + x-oaiMeta: + name: Project group list + example: | + { + "object": "list", + "data": [ + { + "object": "project.group", + "project_id": "proj_abc123", + "group_id": "group_01J1F8ABCDXYZ", + "group_name": "Support Team", + "created_at": 1711471533 + } + ], + "has_more": false, + "next": null + } ProjectListResponse: type: object properties: @@ -44693,6 +47018,131 @@ components: variables: $ref: '#/components/schemas/ResponsePromptVariables' - type: 'null' + PublicAssignOrganizationGroupRoleBody: + type: object + description: Request payload for assigning a role to a group or user. + properties: + role_id: + type: string + description: Identifier of the role to assign. + required: + - role_id + x-oaiMeta: + example: | + { + "role_id": "role_01J1F8ROLE01" + } + PublicCreateOrganizationRoleBody: + type: object + description: Request payload for creating a custom role. + properties: + role_name: + type: string + description: Unique name for the role. + permissions: + type: array + description: Permissions to grant to the role. + items: + type: string + description: + description: Optional description of the role. + anyOf: + - type: string + - type: 'null' + required: + - role_name + - permissions + x-oaiMeta: + example: | + { + "role_name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "description": "Allows managing organization groups" + } + PublicRoleListResource: + type: object + description: Paginated list of roles available on an organization or project. + properties: + object: + type: string + enum: + - list + description: Always `list`. + x-stainless-const: true + data: + type: array + description: Roles returned in the current page. + items: + $ref: '#/components/schemas/Role' + has_more: + type: boolean + description: Whether more roles are available when paginating. + next: + description: Cursor to fetch the next page of results, or `null` when there are no additional roles. + anyOf: + - type: string + - type: 'null' + required: + - object + - data + - has_more + - next + x-oaiMeta: + name: Role list + example: | + { + "object": "list", + "data": [ + { + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false + } + ], + "has_more": false, + "next": null + } + PublicUpdateOrganizationRoleBody: + type: object + description: Request payload for updating an existing role. + properties: + permissions: + description: Updated set of permissions for the role. + anyOf: + - type: array + items: + type: string + - type: 'null' + description: + description: New description for the role. + anyOf: + - type: string + - type: 'null' + role_name: + description: New name for the role. + anyOf: + - type: string + - type: 'null' + x-oaiMeta: + example: | + { + "role_name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "description": "Allows managing organization groups" + } RealtimeAudioFormats: anyOf: - type: object @@ -56082,6 +58532,147 @@ components: "item_id": "ws_123", "sequence_number": 0 } + Role: + type: object + description: Details about a role that can be assigned through the public Roles API. + properties: + object: + type: string + enum: + - role + description: Always `role`. + x-stainless-const: true + id: + type: string + description: Identifier for the role. + name: + type: string + description: Unique name for the role. + description: + description: Optional description of the role. + anyOf: + - type: string + - type: 'null' + permissions: + type: array + description: Permissions granted by the role. + items: + type: string + resource_type: + type: string + description: Resource type the role is bound to (for example `api.organization` or `api.project`). + predefined_role: + type: boolean + description: Whether the role is predefined and managed by OpenAI. + required: + - object + - id + - name + - description + - permissions + - resource_type + - predefined_role + x-oaiMeta: + name: The role object + example: | + { + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false + } + RoleDeletedResource: + type: object + description: Confirmation payload returned after deleting a role. + properties: + object: + type: string + enum: + - role.deleted + description: Always `role.deleted`. + x-stainless-const: true + id: + type: string + description: Identifier of the deleted role. + deleted: + type: boolean + description: Whether the role was deleted. + required: + - object + - id + - deleted + x-oaiMeta: + name: Role deletion confirmation + example: | + { + "object": "role.deleted", + "id": "role_01J1F8ROLE01", + "deleted": true + } + RoleListResource: + type: object + description: Paginated list of roles assigned to a principal. + properties: + object: + type: string + enum: + - list + description: Always `list`. + x-stainless-const: true + data: + type: array + description: Role assignments returned in the current page. + items: + $ref: '#/components/schemas/AssignedRoleDetails' + has_more: + type: boolean + description: Whether additional assignments are available when paginating. + next: + description: Cursor to fetch the next page of results, or `null` when there are no more assignments. + anyOf: + - type: string + - type: 'null' + required: + - object + - data + - has_more + - next + x-oaiMeta: + name: Assigned role list + example: | + { + "object": "list", + "data": [ + { + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false, + "description": "Allows managing organization groups", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": { + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com" + }, + "metadata": {} + } + ], + "has_more": false, + "next": null + } RunCompletionUsage: anyOf: - type: object @@ -58449,6 +61040,22 @@ components: required: - type - text + UpdateGroupBody: + type: object + description: Request payload for updating the details of an existing group. + properties: + name: + type: string + description: New display name for the group. + minLength: 1 + maxLength: 255 + required: + - name + x-oaiMeta: + example: | + { + "name": "Escalations" + } UpdateVectorStoreFileAttributesRequest: type: object additionalProperties: false @@ -59123,6 +61730,52 @@ components: - object - id - deleted + UserListResource: + type: object + description: Paginated list of user objects returned when inspecting group membership. + properties: + object: + type: string + enum: + - list + description: Always `list`. + x-stainless-const: true + data: + type: array + description: Users in the current page. + items: + $ref: '#/components/schemas/User' + has_more: + type: boolean + description: Whether more users are available when paginating. + next: + description: Cursor to fetch the next page of results, or `null` when no further users are available. + anyOf: + - type: string + - type: 'null' + required: + - object + - data + - has_more + - next + x-oaiMeta: + name: Group user list + example: | + { + "object": "list", + "data": [ + { + "object": "organization.user", + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com", + "role": "owner", + "added_at": 1711471533 + } + ], + "has_more": false, + "next": null + } UserListResponse: type: object properties: @@ -59147,6 +61800,50 @@ components: - first_id - last_id - has_more + UserRoleAssignment: + type: object + description: Role assignment linking a user to a role. + properties: + object: + type: string + enum: + - user.role + description: Always `user.role`. + x-stainless-const: true + user: + $ref: '#/components/schemas/User' + role: + $ref: '#/components/schemas/Role' + required: + - object + - user + - role + x-oaiMeta: + name: The user role object + example: | + { + "object": "user.role", + "user": { + "object": "organization.user", + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com", + "role": "owner", + "added_at": 1711470000 + }, + "role": { + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false + } + } UserRoleUpdateRequest: type: object properties: @@ -61764,6 +64461,7 @@ components: - id - call_id - status + - operation title: Apply patch tool call description: A tool call that applies file diffs by creating, deleting, or updating files. ApplyPatchCallOutputStatus: @@ -61803,7 +64501,6 @@ components: - id - call_id - status - - output title: Apply patch tool call output description: The output emitted by an apply patch tool call. MCPToolCallStatus: @@ -62323,9 +65020,11 @@ components: $ref: '#/components/schemas/ApplyPatchCallOutputStatusParam' description: The status of the apply patch tool call output. One of `completed` or `failed`. output: - type: string - maxLength: 10485760 - description: Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + anyOf: + - type: string + maxLength: 10485760 + description: Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - type: 'null' type: object required: - type @@ -66280,6 +68979,122 @@ x-oaiMeta: - type: object key: User path: object + - id: groups + title: Groups + description: > + Manage reusable collections of users for organization-wide access control and maintain their + membership. + navigationGroup: administration + sections: + - type: endpoint + key: list-groups + path: list + - type: endpoint + key: create-group + path: create + - type: endpoint + key: update-group + path: update + - type: endpoint + key: delete-group + path: delete + - type: endpoint + key: list-group-users + path: users/list + - type: endpoint + key: add-group-user + path: users/add + - type: endpoint + key: remove-group-user + path: users/delete + - type: object + key: GroupUserAssignment + path: users/assignment-object + - type: object + key: Group + path: object + - id: roles + title: Roles + description: > + Create and manage custom roles that can be assigned to groups and users at the organization or project + level. + navigationGroup: administration + sections: + - type: endpoint + key: list-roles + path: list + - type: endpoint + key: create-role + path: create + - type: endpoint + key: update-role + path: update + - type: endpoint + key: delete-role + path: delete + - type: endpoint + key: list-project-roles + path: project/list + - type: endpoint + key: create-project-role + path: project/create + - type: endpoint + key: update-project-role + path: project/update + - type: endpoint + key: delete-project-role + path: project/delete + - type: object + key: Role + path: object + - id: role-assignments + title: Role assignments + description: | + Assign and remove roles for users and groups at the organization or project level. + navigationGroup: administration + sections: + - type: endpoint + key: list-group-role-assignments + path: organization/groups/list + - type: endpoint + key: assign-group-role + path: organization/groups/assign + - type: endpoint + key: unassign-group-role + path: organization/groups/delete + - type: endpoint + key: list-user-role-assignments + path: organization/users/list + - type: endpoint + key: assign-user-role + path: organization/users/assign + - type: endpoint + key: unassign-user-role + path: organization/users/delete + - type: endpoint + key: list-project-group-role-assignments + path: projects/groups/list + - type: endpoint + key: assign-project-group-role + path: projects/groups/assign + - type: endpoint + key: unassign-project-group-role + path: projects/groups/delete + - type: endpoint + key: list-project-user-role-assignments + path: projects/users/list + - type: endpoint + key: assign-project-user-role + path: projects/users/assign + - type: endpoint + key: unassign-project-user-role + path: projects/users/delete + - type: object + key: GroupRoleAssignment + path: objects/group + - type: object + key: UserRoleAssignment + path: objects/user - id: projects title: Projects description: | @@ -66329,6 +69144,24 @@ x-oaiMeta: - type: object key: ProjectUser path: object + - id: project-groups + title: Project groups + description: | + Manage which groups have access to a project and the role they receive. + navigationGroup: administration + sections: + - type: endpoint + key: list-project-groups + path: list + - type: endpoint + key: add-project-group + path: add + - type: endpoint + key: remove-project-group + path: delete + - type: object + key: ProjectGroup + path: object - id: project-service-accounts title: Project service accounts description: >