Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Openai Project group role assignments API
version: 2.3.0
contact:
name: OpenAI Support
url: https://help.openai.com/
license:
name: MIT
identifier: MIT
termsOfService: https://openai.com/policies/terms-of-use
description: 'Operations tagged Project group role assignments across 2 of this provider''s published API definitions: openai-openapi-master-2026-09-23.yml, openai-openapi-master-2026-10-12.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.openai.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Project group role assignments
paths:
/projects/{project_id}/groups/{group_id}/roles:
get:
security:
- AdminApiKeyAuth: []
summary: List project group role assignments
description: Lists the project roles assigned to a group within a project.
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'
'429':
$ref: '#/components/responses/TooManyRequests'
x-oaiMeta:
group: administration
examples:
request:
curl: "curl https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false,\n \"description\": \"Allows managing API keys for the project\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {}\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n"
post:
security:
- AdminApiKeyAuth: []
summary: Assign project role to group
description: Assigns a project role to a group within a project.
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'
'429':
$ref: '#/components/responses/TooManyRequests'
x-oaiMeta:
group: administration
examples:
request:
curl: "curl -X POST https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_id\": \"role_01J1F8PROJ\"\n }'\n"
response: "{\n \"object\": \"group.role\",\n \"group\": {\n \"object\": \"group\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"scim_managed\": false\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n }\n}\n"
servers:
- url: https://api.openai.com/v1
/projects/{project_id}/groups/{group_id}/roles/{role_id}:
get:
security:
- AdminApiKeyAuth: []
summary: Retrieve project group role
description: Retrieves a project role assigned to a group.
operationId: retrieve-project-group-role
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: role_id
in: path
description: The ID of the project role to retrieve for the group.
required: true
schema:
type: string
responses:
'200':
description: Project role retrieved for the group successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/AssignedRoleDetails'
'429':
$ref: '#/components/responses/TooManyRequests'
x-oaiMeta:
group: administration
examples:
request:
curl: "curl https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
response: "{\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false,\n \"description\": \"Allows managing API keys for the project\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": null,\n \"metadata\": {},\n \"assignment_sources\": null\n}\n"
delete:
security:
- AdminApiKeyAuth: []
summary: Unassign project role from group
description: Unassigns a project role from a group within a project.
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'
'429':
$ref: '#/components/responses/TooManyRequests'
x-oaiMeta:
group: administration
examples:
request:
curl: "curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
response: "{\n \"object\": \"group.role.deleted\",\n \"deleted\": true\n}\n"
servers:
- url: https://api.openai.com/v1
components:
schemas:
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: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {},\n \"assignment_sources\": null\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n"
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: unixtime
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: "{\n \"object\": \"group\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"scim_managed\": false\n}\n"
_MisalignmentSteer:
properties:
message:
type: string
description: The public continuation instruction.
type: object
required:
- message
Error:
type: object
properties:
code:
anyOf:
- type: string
- type: 'null'
message:
type: string
param:
anyOf:
- type: string
- type: 'null'
type:
type: string
misalignment:
$ref: '#/components/schemas/MisalignmentErrorDetailsResource'
required:
- type
- message
- param
- code
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: "{\n \"object\": \"group.role.deleted\",\n \"deleted\": true\n}\n"
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: unixtime
- type: 'null'
updated_at:
description: When the role was last updated.
anyOf:
- type: integer
format: unixtime
- 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'
assignment_sources:
description: Principals from which the role assignment is inherited, when available.
anyOf:
- type: array
items:
type: object
properties:
principal_id:
type: string
principal_type:
type: string
required:
- principal_id
- principal_type
- type: 'null'
required:
- id
- name
- permissions
- resource_type
- predefined_role
- description
- created_at
- updated_at
- created_by
- created_by_user_obj
- metadata
- assignment_sources
_MisalignmentErrorType:
anyOf:
- type: string
- type: string
enum:
- potentially_unintended_data_transfer
- potentially_unintended_data_access
- potentially_unintended_destructive_activity
- other
ErrorResponse:
type: object
properties:
error:
$ref: '#/components/schemas/Error'
required:
- error
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: "{\n \"object\": \"group.role\",\n \"group\": {\n \"object\": \"group\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"scim_managed\": false\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n }\n}\n"
MisalignmentErrorDetailsResource:
properties:
error_type:
$ref: '#/components/schemas/_MisalignmentErrorType'
description: An optional classification; clients must accept additional values.
detailed_explanation:
type: string
description: The public explanation for this block.
steer:
$ref: '#/components/schemas/_MisalignmentSteer'
description: An optional public continuation instruction.
type: object
required: []
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: "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n}\n"
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: "{\n \"role_id\": \"role_01J1F8ROLE01\"\n}\n"
PermissionErrorResponse:
type: object
properties:
error:
description: Details about the permission error.
anyOf:
- $ref: '#/components/schemas/Error'
- type: string
description: An explanation of the missing API permissions.
required:
- error
MisalignmentErrorDetailsResource_2:
properties:
review_target:
anyOf:
- not:
pattern: '[^A-Za-z0-9._~:-]'
type: string
maxLength: 96
minLength: 1
pattern: ^[A-Za-z0-9._~:-]+$
description: An opaque target for explicitly continuing this review, or null when unavailable.
- type: 'null'
error_type:
$ref: '#/components/schemas/_MisalignmentErrorType'
description: An optional classification; clients must accept additional values.
detailed_explanation:
type: string
description: The public explanation for this block.
steer:
$ref: '#/components/schemas/_MisalignmentSteer'
description: An optional public continuation instruction.
type: object
required: []
responses:
TooManyRequests:
description: The request was rejected because a rate limit was exceeded.
headers:
Retry-After:
description: The minimum number of seconds to wait before retrying. This header is returned when the server has computed a retry delay and may be omitted for 429 responses that require user action.
schema:
type: integer
minimum: 1
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
AdminApiKeyAuth:
type: http
scheme: bearer
x-refined-from:
- openai-openapi-master-2026-09-23.yml
- openai-openapi-master-2026-10-12.yml
x-oaiMeta:
groups:
- id: audio
title: Audio
description: 'Learn how to turn audio into text or text into audio.
Related guide: [Speech to text](/docs/guides/speech-to-text)
'
sections:
- type: endpoint
key: createSpeech
path: createSpeech
- type: endpoint
key: createTranscription
path: createTranscription
- type: endpoint
key: createTranslation
path: createTranslation
- id: chat
title: Chat
description: 'Given a list of messages comprising a conversation, the model will return a response.
Related guide: [Chat Completions](/docs/guides/text-generation)
'
sections:
- type: endpoint
key: createChatCompletion
path: create
- type: object
key: CreateChatCompletionResponse
path: object
- type: object
key: CreateChatCompletionStreamResponse
path: streaming
- id: embeddings
title: Embeddings
description: 'Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms.
Related guide: [Embeddings](/docs/guides/embeddings)
'
sections:
- type: endpoint
key: createEmbedding
path: create
- type: object
key: Embedding
path: object
- id: fine-tuning
title: Fine-tuning
description: 'Manage fine-tuning jobs to tailor a model to your specific training data.
Related guide: [Fine-tune models](/docs/guides/fine-tuning)
'
sections:
- type: endpoint
key: createFineTuningJob
path: create
- type: endpoint
key: listPaginatedFineTuningJobs
path: list
- type: endpoint
key: listFineTuningEvents
path: list-events
- type: endpoint
key: retrieveFineTuningJob
path: retrieve
- type: endpoint
key: cancelFineTuningJob
path: cancel
- type: object
key: FineTuningJob
path: object
- type: object
key: FineTuningJobEvent
path: event-object
- id: files
title: Files
description: 'Files are used to upload documents that can be used with features like [Assistants](/docs/api-reference/assistants) and [Fine-tuning](/docs/api-reference/fine-tuning).
'
sections:
- type: endpoint
key: createFile
path: create
- type: endpoint
key: listFiles
path: list
- type: endpoint
key: retrieveFile
path: retrieve
- type: endpoint
key: deleteFile
path: delete
- type: endpoint
key: downloadFile
path: retrieve-contents
- type: object
key: OpenAIFile
path: object
- id: images
title: Images
description: 'Given a prompt and/or an input image, the model will generate a new image.
Related guide: [Image generation](/docs/guides/images)
'
sections:
- type: endpoint
key: createImage
path: create
- type: endpoint
key: createImageEdit
path: createEdit
- type: endpoint
key: createImageVariation
path: createVariation
- type: object
key: Image
path: object
- id: models
title: Models
description: 'List and describe the various models available in the API. You can refer to the [Models](/docs/models) documentation to understand what models are available and the differences between them.
'
sections:
- type: endpoint
key: listModels
path: list
- type: endpoint
key: retrieveModel
path: retrieve
- type: endpoint
key: deleteModel
path: delete
- type: object
key: Model
path: object
- id: moderations
title: Moderations
description: 'Given a input text, outputs if the model classifies it as violating OpenAI''s content policy.
Related guide: [Moderations](/docs/guides/moderation)
'
sections:
- type: endpoint
key: createModeration
path: create
- type: object
key: CreateModerationResponse
path: object
- id: assistants
title: Assistants
beta: true
description: 'Build assistants that can call models and use tools to perform tasks.
[Get started with the Assistants API](/docs/assistants)
'
sections:
- type: endpoint
key: createAssistant
path: createAssistant
- type: endpoint
key: createAssistantFile
path: createAssistantFile
- type: endpoint
key: listAssistants
path: listAssistants
- type: endpoint
key: listAssistantFiles
path: listAssistantFiles
- type: endpoint
key: getAssistant
path: getAssistant
- type: endpoint
key: getAssistantFile
path: getAssistantFile
- type: endpoint
key: modifyAssistant
path: modifyAssistant
- type: endpoint
key: deleteAssistant
path: deleteAssistant
- type: endpoint
key: deleteAssistantFile
path: deleteAssistantFile
- type: object
key: AssistantObject
path: object
- type: object
key: AssistantFileObject
path: file-object
- id: threads
title: Threads
beta: true
description: 'Create threads that assistants can interact with.
Related guide: [Assistants](/docs/assistants/overview)
'
sections:
- type: endpoint
key: createThread
path: createThread
- type: endpoint
key: getThread
path: getThread
- type: endpoint
key: modifyThread
path: modifyThread
- type: endpoint
key: deleteThread
path: deleteThread
- type: object
key: ThreadObject
path: object
- id: messages
title: Messages
beta: true
description: 'Create messages within threads
Related guide: [Assistants](/docs/assistants/overview)
'
sections:
- type: endpoint
key: createMessage
path: createMessage
- type: endpoint
key: listMessages
path: listMessages
- type: endpoint
key: listMessageFiles
path: listMessageFiles
- type: endpoint
key: getMessage
path: getMessage
- type: endpoint
key: getMessageFile
path: getMessageFile
- type: endpoint
key: modifyMessage
path: modifyMessage
- type: object
key: MessageObject
path: object
- type: object
key: MessageFileObject
path: file-object
- id: runs
title: Runs
beta: true
description: 'Represents an execution run on a thread.
Related guide: [Assistants](/docs/assistants/overview)
'
sections:
- type: endpoint
key: createRun
path: createRun
- type: endpoint
key: createThreadAndRun
path: createThreadAndRun
- type: endpoint
key: listRuns
path: listRuns
- type: endpoint
key: listRunSteps
path: listRunSteps
- type: endpoint
key: getRun
path: getRun
- type: endpoint
key: getRunStep
path: getRunStep
- type: endpoint
key: modifyRun
path: modifyRun
- type: endpoint
key: submitToolOuputsToRun
path: submitToolOutputs
- type: endpoint
key: cancelRun
path: cancelRun
- type: object
key: RunObject
path: object
- type: object
key: RunStepObject
path: step-object
- id: completions
title: Completions
legacy: true
description: 'Given a prompt, the model will return one or more predicted completions along with the probabilities of alternative tokens at each position. Most developer should use our [Chat Completions API](/docs/guides/text-generation/text-generation-models) to leverage our best and newest models. Most models that support the legacy Completions endpoint [will be shut off on January 4th, 2024](/docs/deprecations/2023-07-06-gpt-and-embeddings).
'
sections:
- type: endpoint
key: createCompletion
path: create
- type: object
key: CreateCompletionResponse
path: object