Coactive AI userManagement API
The userManagement API from Coactive AI — 6 operation(s) for usermanagement.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Reference agentic-search > agenticSearch userManagement API
version: 1.0.0
servers:
- url: https://api.coactive.ai
description: Production
- url: https://app.coactive.ai
description: Production
tags:
- name: userManagement
paths:
/api/v1/auth-management/user-invitations:
post:
operationId: create-invitation
summary: Create Invitation
description: 'Create a new user invitation.
This endpoint creates a new invitation for a user to join the organization.
The invitation will be sent to the specified email address.'
tags:
- userManagement
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'201':
description: The created invitation details
content:
application/json:
schema:
$ref: '#/components/schemas/UserInvitation'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError1'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserInvitationRequest'
get:
operationId: list-invitations
summary: List Invitations
description: 'List all pending user invitations.
This endpoint retrieves a list of all pending invitations in the organization.'
tags:
- userManagement
parameters:
- name: offset
in: query
description: Number of records to skip (for pagination)
required: false
schema:
type: integer
default: 0
- name: limit
in: query
description: Number of invitations to return
required: false
schema:
type: integer
default: 100
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: A paginated list of pending user invitations
content:
application/json:
schema:
$ref: '#/components/schemas/UserInvitationListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError1'
/api/v1/auth-management/user-invitations/{invitation_id}:
delete:
operationId: delete-invitation
summary: Delete Invitation
description: 'Delete a user invitation.
This endpoint cancels a pending invitation before it is accepted.
The invitation will no longer be valid.'
tags:
- userManagement
parameters:
- name: invitation_id
in: path
description: The unique identifier of the invitation to delete
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError1'
get:
operationId: get-invitation
summary: Get Invitation
description: 'Get a user invitation.
Get the details of a pending user invitation.'
tags:
- userManagement
parameters:
- name: invitation_id
in: path
description: The unique identifier of the invitation to retrieve
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: The details of a pending user invitation
content:
application/json:
schema:
$ref: '#/components/schemas/UserInvitation'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError1'
/api/v1/auth-management/roles:
get:
operationId: list-roles
summary: List Roles
description: 'List all assignable roles.
The roles returned are scoped to the roles context.
For example, if the roles_context is "dataset:123", the endpoint will return all roles
that are assignable to dataset with id "123". If the roles_context is "system", the endpoint
will return all system-level roles that are assignable in the organization.
If no roles_context is provided, the endpoint will return all system-level and dataset-level
roles in the organization.'
tags:
- userManagement
parameters:
- name: roles_context
in: query
description: Context for the roles to include in the response. This can either be 'system' for system-level roles or 'dataset:{dataset_id}' for dataset-level roles.
required: false
schema:
type:
- string
- 'null'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: A list of assignable roles
content:
application/json:
schema:
$ref: '#/components/schemas/RolesListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError1'
/api/v1/auth-management/users:
get:
operationId: list-users
summary: List Users
description: 'List users in the organization.
This endpoint retrieves a paginated list of users in the organization.
The response can be filtered by a search query and optionally include user roles.'
tags:
- userManagement
parameters:
- name: query
in: query
description: Search query to match names and emails
required: false
schema:
type:
- string
- 'null'
- name: user_ids
in: query
description: List of user IDs to filter by
required: false
schema:
type:
- array
- 'null'
items:
type: string
- name: offset
in: query
description: Number of records to skip (for pagination)
required: false
schema:
type: integer
default: 0
- name: limit
in: query
description: Number of users to return
required: false
schema:
type: integer
default: 100
- name: include_roles
in: query
description: Include user roles in the response
required: false
schema:
type: boolean
default: false
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: A paginated list of users in the organization
content:
application/json:
schema:
$ref: '#/components/schemas/UsersListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError1'
/api/v1/auth-management/users/{user_id}:
delete:
operationId: remove-user
summary: Remove User
description: 'Remove a user from the organization.
This endpoint permanently removes a user from the organization.
The user will no longer have access to any organization resources.'
tags:
- userManagement
parameters:
- name: user_id
in: path
description: The ID of the user to remove
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError1'
/api/v1/auth-management/users/{user_id}/roles:
put:
operationId: update-user-roles
summary: Update User Roles
description: 'Replace a user''s roles.
This endpoint allows administrators to replace the roles assigned to a user.
The roles can be scoped to a specific context (e.g., dataset or system).
If a context is provided, the roles will only be replaced within that context.
If no context is provided, all roles (system-level and dataset-level) will be replaced.
To replace roles at the system level, use the "system" context.
To replace roles at the dataset level, use the "dataset:{dataset_id}" context.'
tags:
- userManagement
parameters:
- name: user_id
in: path
description: The ID of the user to update
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: The updated user profile with new roles
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError1'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRolesRequest'
components:
schemas:
RoleDefinition:
type: object
properties:
role_id:
type: string
description: Unique identifier for the role
name:
type: string
description: Display name of the role
description:
type:
- string
- 'null'
description: Optional description of the role's purpose
resource:
type:
- string
- 'null'
description: Optional resource type this role applies to
required:
- role_id
- name
description: Role definition model for available roles
title: RoleDefinition
SortDirection1:
type: string
enum:
- asc
- desc
description: Possible sort orders
title: SortDirection1
HTTPValidationError1:
type: object
properties:
detail:
type: array
items:
$ref: '#/components/schemas/ValidationError1'
title: HTTPValidationError1
UsersListResponse:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/PartialUserResponse'
description: List of users with partial information
meta:
$ref: '#/components/schemas/PagedMeta'
description: Pagination metadata for the response
required:
- users
- meta
description: 'Response model for listing users with pagination.
This model contains a paginated list of users with partial information and
metadata about the pagination. It is used for endpoints that return multiple
users with their basic information.'
title: UsersListResponse
UserResponse:
type: object
properties:
user_id:
type: string
description: Unique identifier for the user
name:
type: string
description: Display name of the user
email:
type:
- string
- 'null'
description: Email address of the user
picture:
type:
- string
- 'null'
description: URL to the user's profile picture
created_at:
type: string
format: date-time
description: Timestamp when the user was created
last_login:
type:
- string
- 'null'
format: date-time
description: Timestamp of the user's last login
roles:
type: array
items:
$ref: '#/components/schemas/Role'
description: List of roles assigned to the user
required:
- user_id
- name
- created_at
- roles
description: 'Complete user response model including roles.
This model extends the base user response to include the user''s assigned roles.
It is used when the complete user information, including roles, is required.'
title: UserResponse
SortItem1:
type: object
properties:
direction:
$ref: '#/components/schemas/SortDirection1'
description: Sort direction (ascending or descending)
field:
type: string
description: Field name to sort by
required:
- direction
- field
description: Metadata about the sort order of the response
title: SortItem1
ValidationError1LocItems:
oneOf:
- type: string
- type: integer
title: ValidationError1LocItems
PagedLinks:
type: object
properties:
prev:
type:
- string
- 'null'
description: URL for the previous page
next:
type:
- string
- 'null'
description: URL for the next page
first:
type:
- string
- 'null'
description: URL for the first page
last:
type:
- string
- 'null'
description: URL for the last page
description: Metadata for retrieving paginated data
title: PagedLinks
PagedMeta:
type: object
properties:
page:
$ref: '#/components/schemas/PagedPageDetails'
description: Current page number (1-indexed)
links:
$ref: '#/components/schemas/PagedLinks'
description: Links to the previous, next, first, and last pages
sort:
type: array
items:
$ref: '#/components/schemas/SortItem1'
description: Sort order for the response
required:
- page
- links
- sort
description: Metadata for paginated responses
title: PagedMeta
Inviter:
type: object
properties:
name:
type: string
description: Display name of the inviter
required:
- name
description: 'Model representing the user who sent the invitation.
This model contains the details of the user who sent the invitation, including
their display name.'
title: Inviter
PagedPageDetails:
type: object
properties:
current_page:
type: integer
description: Current page number (1-indexed)
last_page:
type:
- integer
- 'null'
description: Last page number (if total is known)
limit:
type: integer
description: Number of items per page
offset:
type: integer
description: Offset of the first item in the current page
total:
type:
- integer
- 'null'
description: Total number of items across all pages
required:
- current_page
- limit
- offset
description: Pagination metadata
title: PagedPageDetails
UserInvitationListResponse:
type: object
properties:
user_invitations:
type: array
items:
$ref: '#/components/schemas/UserInvitation'
description: List of pending invitations
meta:
$ref: '#/components/schemas/PagedMeta'
description: Pagination metadata for the response
required:
- user_invitations
- meta
description: 'Response model for listing user invitations.
This model contains a list of pending user invitations and metadata about the
pagination of the results. Each invitation includes details about who sent it,
who it was sent to, and the roles that will be assigned upon acceptance.'
title: UserInvitationListResponse
UserInvitation:
type: object
properties:
invitation_id:
type: string
description: Unique identifier for the invitation
inviter:
$ref: '#/components/schemas/Inviter'
description: Details about the user who sent the invitation
invitee:
$ref: '#/components/schemas/Invitee'
description: Details about the user being invited
invitation_url:
type: string
description: URL for the user to accept the invitation
created_at:
type: string
description: Timestamp when the invitation was created
expires_at:
type: string
description: Timestamp when the invitation expires
roles:
type: array
items:
$ref: '#/components/schemas/Role'
description: List of roles that will be assigned upon acceptance
required:
- invitation_id
- inviter
- invitee
- invitation_url
- created_at
- expires_at
- roles
description: 'Model representing a user invitation.
This model contains the details of an invitation sent to a user, including the
invitation ID, who sent it, who it was sent to, and the roles that will be
assigned upon acceptance. The invitation URL is included for the user to accept
the invitation.'
title: UserInvitation
Invitee:
type: object
properties:
email:
type: string
description: Email address of the invitee
name:
type: string
description: Display name of the invitee
roles:
type: array
items:
$ref: '#/components/schemas/Role'
description: List of roles to assign to the invitee
required:
- email
- name
- roles
title: Invitee
ValidationError1:
type: object
properties:
loc:
type: array
items:
$ref: '#/components/schemas/ValidationError1LocItems'
msg:
type: string
type:
type: string
required:
- loc
- msg
- type
title: ValidationError1
Role:
type: object
properties:
role_id:
type: string
description: Name of the role (e.g., 'admin', 'editor', 'viewer')
resource:
type:
- string
- 'null'
description: Optional resource type the role applies to (e.g., 'dataset')
resource_instance:
type:
- string
- 'null'
description: Optional resource instance ID the role applies to
required:
- role_id
description: Role model for user and client roles
title: Role
RolesListResponse:
type: object
properties:
roles:
type: array
items:
$ref: '#/components/schemas/RoleDefinition'
description: List of roles
required:
- roles
description: Response model for listing all available roles.
title: RolesListResponse
CreateUserInvitationRequest:
type: object
properties:
name:
type: string
description: Display name for the invited user
email:
type: string
description: Email address to send the invitation to
roles:
type: array
items:
$ref: '#/components/schemas/Role'
description: List of roles to assign to the user
required:
- name
- email
description: 'Request model for creating a new user invitation.
This model is used to invite a new user to join an organization. The invitation
will be sent to the specified email address and will include the roles that will
be assigned to the user upon acceptance.'
title: CreateUserInvitationRequest
UpdateUserRolesRequest:
type: object
properties:
roles:
type: array
items:
$ref: '#/components/schemas/Role'
description: New list of roles to assign to the user
roles_context:
type:
- string
- 'null'
description: Context for the roles to update. This can either be 'system' for system-level roles or 'dataset:{dataset_id}' for dataset-level roles.
required:
- roles
description: 'Request model for updating user roles.
This model is used when modifying a user''s role assignments. It allows for
updating the complete list of roles and optionally specifying the context
where these roles apply. For example, if the "system" context is used, the roles
provided will only replace roles at the system level (ex. dataset
roles would remain unchanged). If no context is provided, the role provided in the
request will replace all roles for the user.'
title: UpdateUserRolesRequest
PartialUserResponse:
type: object
properties:
user_id:
type: string
description: Unique identifier for the user
name:
type: string
description: Display name of the user
email:
type:
- string
- 'null'
description: Email address of the user
picture:
type:
- string
- 'null'
description: URL to the user's profile picture
created_at:
type: string
format: date-time
description: Timestamp when the user was created
last_login:
type:
- string
- 'null'
format: date-time
description: Timestamp of the user's last login
roles:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/Role'
description: Optional list of roles assigned to the user
required:
- user_id
- name
- created_at
description: 'Partial user response model with optional roles.
This model extends the base user response with optional roles. It is used
when roles information may not be available or required in the response.'
title: PartialUserResponse
securitySchemes:
HTTPBearer:
type: http
scheme: bearer