OpenAI

OpenAI Roles API

The Roles API from OpenAI — 4 operation(s) for roles.

Documentation GitHub OpenAPI

Business capability

Operations 10

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /organization/roles List the organization's roles · List organization roles #

Ask an LLM

“Which roles are configured at the organization level?”

“Can I see the custom organization roles we've defined?”

Tell an agent

List the organization roles.

Show {limit} organization-wide roles ordered {order}.

POST /organization/roles Create a custom organization role · Create organization role #

Ask an LLM

“How do I define a custom role for my whole organization?”

“Which permissions can I bundle into a new organization role?”

Tell an agent

Create an organization role {role_name} with permissions {permissions}.

Add org-wide role {role_name} granting {permissions}, described as {description}.

GET /organization/roles/{role_id} Retrieve organization role #

POST /organization/roles/{role_id} Update an organization role · Update organization role #

Ask an LLM

“Can I change the permissions on an existing organization role?”

“Is it possible to rename a custom role at the org level?”

Tell an agent

Set organization role {role_id}'s permissions to {permissions}.

Rename organization role {role_id} to {role_name}.

DELETE /organization/roles/{role_id} Delete a custom organization role · Delete organization role #

Ask an LLM

“How do I remove a custom role from the organization?”

“Can I delete an organization role we no longer use?”

Tell an agent destructive · confirm first

Delete organization role {role_id}.

Remove custom org role {role_id}.

GET /projects/{project_id}/roles List the roles in a project · List project roles #

Ask an LLM

“Which roles are defined inside a particular project?”

“Can I see the custom roles available in one project?”

Tell an agent

List the roles in project {project_id}.

Show {limit} roles configured for project {project_id}.

POST /projects/{project_id}/roles Create a custom role in a project · Create project role #

Ask an LLM

“How do I create a role that only applies within one project?”

“Can a project have its own custom set of permissions?”

Tell an agent

Create role {role_name} in project {project_id} with permissions {permissions}.

Add a project-scoped role {role_name} to {project_id} granting {permissions}.

GET /projects/{project_id}/roles/{role_id} Retrieve project role #

POST /projects/{project_id}/roles/{role_id} Update a role in a project · Update project role #

Ask an LLM

“Can I change what a project-level role is allowed to do?”

“Is it possible to rename a role inside a project?”

Tell an agent

Set role {role_id} in project {project_id} to permissions {permissions}.

Rename project {project_id}'s role {role_id} to {role_name}.

DELETE /projects/{project_id}/roles/{role_id} Delete a custom role from a project · Delete project role #

Ask an LLM

“How do I delete a custom role from a single project?”

“Can I remove a project role that nobody uses anymore?”

Tell an agent destructive · confirm first

Delete role {role_id} from project {project_id}.

Remove project {project_id}'s custom role {role_id}.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/openai:openai-roles-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: OpenAI Roles API
  description: The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference for more details.
  version: 2.3.0
  termsOfService: https://openai.com/policies/terms-of-use
  contact:
    name: OpenAI Support
    url: https://help.openai.com/
  license:
    name: MIT
    identifier: MIT
servers:
- url: https://api.openai.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Roles
paths:
  /organization/roles:
    get:
      security:
      - AdminApiKeyAuth: []
      summary: List organization roles
      description: Lists the roles configured for the organization.
      operationId: list-roles
      tags:
      - Roles
      parameters:
      - 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: Roles listed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicRoleListResource'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-oaiMeta:
        group: administration
        examples:
          request:
            curl: "curl https://api.openai.com/v1/organization/roles?limit=20 \\\n  -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n  -H \"Content-Type: application/json\"\n"
          response: "{\n    \"object\": \"list\",\n    \"data\": [\n        {\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    \"has_more\": false,\n    \"next\": null\n}\n"
    post:
      security:
      - AdminApiKeyAuth: []
      summary: Create organization role
      description: Creates a custom role for the organization.
      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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-oaiMeta:
        group: administration
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/organization/roles \\\n  -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n      \"role_name\": \"API Group Manager\",\n      \"permissions\": [\n          \"api.groups.read\",\n          \"api.groups.write\"\n      ],\n      \"description\": \"Allows managing organization groups\"\n  }'\n"
          response: "{\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"
  /organization/roles/{role_id}:
    get:
      security:
      - AdminApiKeyAuth: []
      summary: Retrieve organization role
      description: Retrieves an organization role.
      operationId: retrieve-role
      tags:
      - Roles
      parameters:
      - name: role_id
        in: path
        description: The ID of the role to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Role retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-oaiMeta:
        group: administration
        examples:
          request:
            curl: "curl https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \\\n  -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n  -H \"Content-Type: application/json\"\n"
          response: "{\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"
    post:
      security:
      - AdminApiKeyAuth: []
      summary: Update organization role
      description: Updates an existing 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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-oaiMeta:
        group: administration
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \\\n  -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n      \"role_name\": \"API Group Manager\",\n      \"permissions\": [\n          \"api.groups.read\",\n          \"api.groups.write\"\n      ],\n      \"description\": \"Allows managing organization groups\"\n  }'\n"
          response: "{\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"
    delete:
      security:
      - AdminApiKeyAuth: []
      summary: Delete organization role
      description: Deletes a custom role from the organization.
      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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-oaiMeta:
        group: administration
        examples:
          request:
            curl: "curl -X DELETE https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \\\n  -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n  -H \"Content-Type: application/json\"\n"
          response: "{\n    \"object\": \"role.deleted\",\n    \"id\": \"role_01J1F8ROLE01\",\n    \"deleted\": true\n}\n"
  /projects/{project_id}/roles:
    get:
      security:
      - AdminApiKeyAuth: []
      summary: List project roles
      description: Lists the roles configured for a project.
      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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-oaiMeta:
        group: administration
        examples:
          request:
            curl: "curl https://api.openai.com/v1/projects/proj_abc123/roles?limit=20 \\\n  -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n  -H \"Content-Type: application/json\"\n"
          response: "{\n    \"object\": \"list\",\n    \"data\": [\n        {\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    \"has_more\": false,\n    \"next\": null\n}\n"
    post:
      security:
      - AdminApiKeyAuth: []
      summary: Create project role
      description: Creates a custom role for a project.
      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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-oaiMeta:
        group: administration
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles \\\n  -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n      \"role_name\": \"API Project Key Manager\",\n      \"permissions\": [\n          \"api.organization.projects.api_keys.read\",\n          \"api.organization.projects.api_keys.write\"\n      ],\n      \"description\": \"Allows managing API keys for the project\"\n  }'\n"
          response: "{\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"
  /projects/{project_id}/roles/{role_id}:
    get:
      security:
      - AdminApiKeyAuth: []
      summary: Retrieve project role
      description: Retrieves a project role.
      operationId: retrieve-project-role
      tags:
      - Roles
      parameters:
      - name: project_id
        in: path
        description: The ID of the project.
        required: true
        schema:
          type: string
      - name: role_id
        in: path
        description: The ID of the role to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Project role retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-oaiMeta:
        group: administration
        examples:
          request:
            curl: "curl https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \\\n  -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n  -H \"Content-Type: application/json\"\n"
          response: "{\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"
    post:
      security:
      - AdminApiKeyAuth: []
      summary: Update project role
      description: Updates an existing 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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-oaiMeta:
        group: administration
        examples:
          request:
            curl: "curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \\\n  -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n      \"role_name\": \"API Project Key Manager\",\n      \"permissions\": [\n          \"api.organization.projects.api_keys.read\",\n          \"api.organization.projects.api_keys.write\"\n      ],\n      \"description\": \"Allows managing API keys for the project\"\n  }'\n"
          response: "{\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"
    delete:
      security:
      - AdminApiKeyAuth: []
      summary: Delete project role
      description: Deletes a custom role from a project.
      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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-oaiMeta:
        group: administration
        examples:
          request:
            curl: "curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \\\n  -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n  -H \"Content-Type: application/json\"\n"
          response: "{\n    \"object\": \"role.deleted\",\n    \"id\": \"role_01J1F8PROJ\",\n    \"deleted\": true\n}\n"
components:
  schemas:
    _MisalignmentErrorType:
      anyOf:
      - type: string
      - type: string
        enum:
        - potentially_unintended_data_transfer
        - potentially_unintended_data_access
        - potentially_unintended_destructive_activity
        - other
    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"
    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: "{\n    \"object\": \"role.deleted\",\n    \"id\": \"role_01J1F8ROLE01\",\n    \"deleted\": true\n}\n"
    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: "{\n    \"role_name\": \"API Group Manager\",\n    \"permissions\": [\n        \"api.groups.read\",\n        \"api.groups.write\"\n    ],\n    \"description\": \"Allows managing organization groups\"\n}\n"
    _MisalignmentSteer:
      properties:
        message:
          type: string
          description: The public continuation instruction.
      type: object
      required:
      - message
    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: "{\n    \"object\": \"list\",\n    \"data\": [\n        {\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    \"has_more\": false,\n    \"next\": null\n}\n"
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
      - error
    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
    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: []
    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: "{\n    \"role_name\": \"API Group Manager\",\n    \"permissions\": [\n        \"api.groups.read\",\n        \"api.groups.write\"\n    ],\n    \"description\": \"Allows managing organization groups\"\n}\n"
  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-oaiMeta:
  navigationGroups:
  - id: responses
    title: Responses API
  - id: webhooks
    title: Webhooks
  - id: endpoints
    title: Platform APIs
  - id: vector_stores
    title: Vector stores
  - id: chatkit
    title: ChatKit
    beta: true
  - id: containers
    title: Containers
  - id: live
    title: Live (alpha)
  - id: realtime
    title: Realtime
  - id: chat
    title: Chat Completions
  - id: assistants
    title: Assistants
    deprecated: true
  - id: administration
    title: Administration
  - id: legacy
    title: Legacy
  groups:
  - id: responses-streaming
    title: Streaming events
    description: 'When you [create a Response](https://developers.openai.com/api/reference/resources/responses/methods/create) with

      `stream` set to `true`, the server will emit server-sent events to the

      client as the Response is generated. This section contains the events that

      are emitted by the server.


      When processing a `compaction_trigger`, `response.compaction.compacting`

      reports newly sampled summary output at most once every 30 seconds. It

      carries no summary content and does not modify the compaction output item.

      The existing `response.output_item.added` and `response.output_item.done`

      events mark that item''s lifecycle; `response.output_item.done` carries its

      final encrypted content. A short compaction may finish without emitting a

      progress event.


      [Learn more about streaming responses](https://developers.openai.com/api/docs/guides/streaming-responses).

      '
    navigationGroup: responses
    sections:
    - type: object
      key: ResponseCreatedEvent
      path: <auto>
    - type: object
      key: ResponseInProgressEvent
      path: <auto>
    - type: object
      key: ResponseCompletedEvent
      path: <auto>
    - type: object
      key: ResponseFailedEvent
      path: <auto>
    - type: object
      key: ResponseIncompleteEvent
      path: <auto>
    - type: object
      key: ResponseOutputItemAddedEvent
      path: <auto>
    - type: object
      key: ResponseOutputItemDoneEvent
      path: <auto>
    - type: object
      key: ResponseCompactionCompactingEvent
      path: <auto>
    - type: object
      key: ResponseContentPartAddedEvent
      path: <auto>
    - type: object
      key: ResponseContentPartDoneEvent
      path: <auto>
    - type: object
      key: ResponseTextDeltaEvent
      path: response/output_text/delta
    - type: object
      key: ResponseTextDoneEvent
      path: response/output_text/done
    - type: object
      key: ResponseRefusalDeltaEvent
      path: <auto>
    - type: object
      key: ResponseRefusalDoneEvent
      path: <auto>
    - type: object
      key: ResponseFunctionCallArgumentsDeltaEvent
      path: <auto>
    - type: object
      key: ResponseFunctionCallArgumentsDoneEvent
      path: <auto>
    - type: object
      key: ResponseFileSearchCallInProgressEvent
      path: <auto>
    - type: object
      key: ResponseFileSearchCallSearchingEvent
      path: <auto>
    - type: object
      key: ResponseFileSearchCallCompletedEvent
      path: <auto>
    - type: object
      key: ResponseWebSearchCallInProgressEvent
      path: <auto>
    - type: object
      key: ResponseWebSearchCallSearchingEvent
      path: <auto>
    - type: object
      key: ResponseWebSearchCallCompletedEvent
      path: <auto>
    - type: object
      key: ResponseReasoningSummaryPartAddedEvent
      path: <auto>
    - type: object
      key: ResponseReasoningSummaryPartDoneEvent
      path: <auto>
    - type: object
      key: ResponseReasoningSummaryTextDeltaEvent
      path: <auto>
    - type: object
      key: ResponseReasoningSummaryTextDoneEvent
      path: <auto>
    - type: object
      key: ResponseReasoningTextDeltaEvent
      path: <auto>
    - type: object
      key: ResponseReasoningTextDoneEvent
      path: <auto>
    - type: object
      key: ResponseImageGenCallCompletedEvent
      path: <auto>
    - type: object
      key: ResponseImageGenCallGeneratingEvent
      path: <auto>
    - type: object
      key: ResponseImageGenCallInProgressEvent
      path: <auto>
    - type: object
      key: ResponseImageGenCallPartialImageEvent
      path: <auto>
    - type: object
      key: ResponseMCPCallArgumentsDeltaEvent
      path: <auto>
    - type: object
      key: ResponseMCPCallArgumentsDoneEvent
      path: <auto>
    - type: object
      key: ResponseMCPCallCompletedEvent
      path: <auto>
    - type: object
      key: ResponseMCPCallFailedEvent
      path: <auto>
    - type: object
      key: ResponseMCPCallInProgressEvent
      path: <auto>
    - type: object
      key: ResponseMCPListToolsCompletedEvent
      path: <auto>
    - type: object
      key: ResponseMCPListToolsFailedEvent
      path: <auto>
    - type: object
      key: ResponseMCPListToolsInProgressEvent
      path: <auto>
    - type: object
      key: ResponseCodeInterpreterCallInProgressEvent
      path: <auto>
    - type: object
      key: ResponseCodeInterpreterCallInterpretingEvent
      path: <auto>
    - type: object
      key: ResponseCodeInterpreterCallCompletedEvent
      path: <auto>
    - type: object
      key: ResponseCodeInterpreterCallCodeDeltaEvent
      path: <auto>
    - type: object
      key: ResponseCodeInterpreterCallCodeDoneEvent
      path: <auto>
    - type: object
      key: ResponseOutputTextAnnotationAddedEvent
      path: <auto>
    - type: object
      key: ResponseQueuedEvent
      path: <auto>
    - type: object
      key: ResponseCustomToolCallInputDeltaEvent
      path: <auto>
    - type: object
      key: ResponseCustomToolCallInputDoneEvent
      path: <auto>
    - type: object
      key: ResponseErrorEvent
      path: <auto>
  - id: responses-websocket-client-events
    title: Client events
    description: 'Events sent by the client over a Responses API WebSocket connection.

      '
    navigationGroup: responses
    sections:
    - type: object
      key: ResponsesClientEventResponseCreate
      path: <auto>
    - type: object
      key: ResponseSteerEvent
      path: <auto>
  - id: responses-websocket-server-events
    title: Server events (WebSocket only)
    description: 'Events emitted only over a Responses API WebSocket connection.

      '
    navigationGroup: responses
    sections:
    - type: object
      key: ResponseSteerAcceptedEvent
      path: <auto>
    - type: object
      key: ResponseSteerPendingEvent
      path: <auto>
    - type: object
      key: ResponseSteerFailedEvent
      path: <auto>


# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/openai-roles-api-openapi.yml

OpenAI Roles API

Operations 10

Documentation

Specifications

Schemas & Data

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification