Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: CallidusAI Authorization API
description: Callidus AI backend API
version: 0.1.0
tags:
- name: Authorization
paths:
/authz/grants:
post:
tags:
- Authorization
summary: Create a permission grant
description: Grant a permission (OWNER, EDITOR, or VIEWER) to a subject on a resource.
operationId: create_grant_authz_grants_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GrantPermissionRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GrantPermissionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Authorization
summary: Upsert a permission grant
description: Create or update a permission grant. If a grant exists, it will be updated with the new relation.
operationId: upsert_grant_authz_grants_put
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GrantPermissionRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GrantPermissionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Authorization
summary: Revoke a permission grant
description: Remove a permission grant from a subject on a resource.
operationId: revoke_grant_authz_grants_delete
parameters:
- name: subject_id
in: query
required: true
schema:
type: string
description: ID of the subject to revoke permission from
title: Subject Id
description: ID of the subject to revoke permission from
- name: relation
in: query
required: true
schema:
type: integer
maximum: 3
minimum: 1
description: 'Relation to revoke: 1=OWNER, 2=EDITOR, 3=VIEWER'
title: Relation
description: 'Relation to revoke: 1=OWNER, 2=EDITOR, 3=VIEWER'
- name: resource_type
in: query
required: true
schema:
type: integer
maximum: 4
minimum: 1
description: Resource type
title: Resource Type
description: Resource type
- name: resource_id
in: query
required: true
schema:
type: string
description: Resource ID
title: Resource Id
description: Resource ID
- name: subject_type
in: query
required: false
schema:
type: integer
maximum: 2
minimum: 1
description: 'Subject type: 1=USER, 2=TEAM'
default: 1
title: Subject Type
description: 'Subject type: 1=USER, 2=TEAM'
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/authz/permissions/members:
get:
tags:
- Authorization
summary: Get resource members
description: 'Get all subjects who have access to a specific resource.
The requesting user must have can_view permission on the resource.'
operationId: get_resource_members_authz_permissions_members_get
deprecated: true
parameters:
- name: resource_type
in: query
required: true
schema:
type: integer
maximum: 4
minimum: 1
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
title: Resource Type
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
- name: resource_id
in: query
required: true
schema:
type: string
description: Resource ID to view members for
title: Resource Id
description: Resource ID to view members for
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceMembersResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/authz/permissions/resources:
get:
tags:
- Authorization
summary: Get user resources
description: Get all resources that the current user has access to.
operationId: get_user_resources_endpoint_authz_permissions_resources_get
parameters:
- name: resource_type
in: query
required: false
schema:
anyOf:
- type: integer
maximum: 4
minimum: 1
- type: 'null'
description: 'Optional filter by resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
title: Resource Type
description: 'Optional filter by resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UserResourcesResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/authz/permissions/check-inherited:
get:
tags:
- Authorization
summary: Check inherited permissions
description: Check if the current user has a permission on a resource via Matter-level inheritance.
operationId: check_inherited_permissions_endpoint_authz_permissions_check_inherited_get
deprecated: true
parameters:
- name: resource_type
in: query
required: true
schema:
type: integer
maximum: 4
minimum: 1
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
title: Resource Type
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
- name: resource_id
in: query
required: true
schema:
type: string
description: Resource ID to check permission for
title: Resource Id
description: Resource ID to check permission for
- name: permission
in: query
required: true
schema:
type: string
description: Permission to check (can_view, can_edit, can_delete, can_manage_members)
title: Permission
description: Permission to check (can_view, can_edit, can_delete, can_manage_members)
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/InheritedPermissionResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/authz/permissions/can:
get:
tags:
- Authorization
summary: Check if permission is allowed
description: 'Simple boolean check: can the current user perform a specific action on a resource?'
operationId: check_permission_allowed_authz_permissions_can_get
parameters:
- name: resource_type
in: query
required: true
schema:
type: integer
maximum: 4
minimum: 1
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
title: Resource Type
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
- name: resource_id
in: query
required: true
schema:
type: string
description: Resource ID to check permission for
title: Resource Id
description: Resource ID to check permission for
- name: permission
in: query
required: true
schema:
type: string
description: Permission to check (can_view, can_edit, can_delete, can_manage_members)
title: Permission
description: Permission to check (can_view, can_edit, can_delete, can_manage_members)
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionCanResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/authz/permissions:
get:
tags:
- Authorization
summary: View permissions (generic)
description: Generic endpoint for permission queries. Prefer /permissions/members, /permissions/resources, or /permissions/can for new integrations.
operationId: get_permissions_authz_permissions_get
deprecated: true
parameters:
- name: resource_type
in: query
required: false
schema:
anyOf:
- type: integer
maximum: 4
minimum: 1
- type: 'null'
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
title: Resource Type
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
- name: resource_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Resource ID to view members for
title: Resource Id
description: Resource ID to view members for
- name: user_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: User ID to view accessible resources for (defaults to current user)
title: User Id
description: User ID to view accessible resources for (defaults to current user)
- name: subject_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Subject ID to check permissions for (Mode 3)
title: Subject Id
description: Subject ID to check permissions for (Mode 3)
- name: subject_type
in: query
required: false
schema:
type: integer
maximum: 2
minimum: 1
description: 'Subject type: 1=USER, 2=TEAM (used with subject_id for Mode 3)'
default: 1
title: Subject Type
description: 'Subject type: 1=USER, 2=TEAM (used with subject_id for Mode 3)'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
PermissionListResponse:
properties:
members:
items:
$ref: '#/components/schemas/PermissionMemberResponse'
type: array
title: Members
description: List of members/permissions for a resource
resources:
items:
$ref: '#/components/schemas/UserResourceResponse'
type: array
title: Resources
description: List of resources a user has access to
subject_permission:
anyOf:
- $ref: '#/components/schemas/SubjectPermissionResponse'
- type: 'null'
description: Permission info for a specific subject on a specific resource (Mode 3)
total:
type: integer
title: Total
description: Total count of items
default: 0
type: object
title: PermissionListResponse
description: Response model for listing permissions.
UserResourcesResponse:
properties:
resources:
items:
$ref: '#/components/schemas/UserResourceResponse'
type: array
title: Resources
description: List of resources the user has access to
user_id:
type: string
title: User Id
description: ID of the user
total:
type: integer
title: Total
description: Total count of resources
type: object
required:
- resources
- user_id
- total
title: UserResourcesResponse
description: Response for /permissions/resources - what resources a user can access.
GrantPermissionResponse:
properties:
id:
type: string
title: Id
description: Unique ID of the permission record
subject_type:
type: integer
title: Subject Type
description: 'Subject type: 1=USER, 2=TEAM'
subject_type_name:
type: string
title: Subject Type Name
description: Human-readable subject type name
subject_id:
type: string
title: Subject Id
description: ID of the subject
relation:
type: integer
title: Relation
description: 'Relation type: 1=OWNER, 2=EDITOR, 3=VIEWER'
relation_name:
type: string
title: Relation Name
description: Human-readable relation name
resource_type:
type: integer
title: Resource Type
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
resource_type_name:
type: string
title: Resource Type Name
description: Human-readable resource type name
resource_id:
type: string
title: Resource Id
description: ID of the resource
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
description: When the permission was created
created_by:
anyOf:
- type: string
- type: 'null'
title: Created By
description: Who created this permission
type: object
required:
- id
- subject_type
- subject_type_name
- subject_id
- relation
- relation_name
- resource_type
- resource_type_name
- resource_id
title: GrantPermissionResponse
description: Response model for a created/updated permission grant.
ResourceMembersResponse:
properties:
members:
items:
$ref: '#/components/schemas/PermissionMemberResponse'
type: array
title: Members
description: List of members/permissions for this resource
resource_type:
type: integer
title: Resource Type
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
resource_type_name:
type: string
title: Resource Type Name
description: Human-readable resource type name
resource_id:
type: string
title: Resource Id
description: ID of the resource
total:
type: integer
title: Total
description: Total count of members
type: object
required:
- members
- resource_type
- resource_type_name
- resource_id
- total
title: ResourceMembersResponse
description: Response for /permissions/members - who has access to a resource.
UserResourceResponse:
properties:
resource_type:
type: integer
title: Resource Type
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
resource_type_name:
type: string
title: Resource Type Name
description: Human-readable resource type name
resource_id:
type: string
title: Resource Id
description: ID of the resource
relation:
type: integer
title: Relation
description: 'Relation type: 1=OWNER, 2=EDITOR, 3=VIEWER'
relation_name:
type: string
title: Relation Name
description: Human-readable relation name
permissions:
items:
type: string
type: array
title: Permissions
description: List of derived permissions (can_view, can_edit, etc.)
type: object
required:
- resource_type
- resource_type_name
- resource_id
- relation
- relation_name
title: UserResourceResponse
description: Response model for a resource that a user has access to.
SubjectPermissionResponse:
properties:
subject_type:
type: integer
title: Subject Type
description: 'Subject type: 1=USER, 2=TEAM'
subject_type_name:
type: string
title: Subject Type Name
description: Human-readable subject type name
subject_id:
type: string
title: Subject Id
description: ID of the subject
resource_type:
type: integer
title: Resource Type
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
resource_type_name:
type: string
title: Resource Type Name
description: Human-readable resource type name
resource_id:
type: string
title: Resource Id
description: ID of the resource
relation:
anyOf:
- type: integer
- type: 'null'
title: Relation
description: 'Relation type: 1=OWNER, 2=EDITOR, 3=VIEWER (None if no direct grant)'
relation_name:
anyOf:
- type: string
- type: 'null'
title: Relation Name
description: Human-readable relation name
permissions:
items:
type: string
type: array
title: Permissions
description: List of derived permissions (can_view, can_edit, etc.)
has_access:
type: boolean
title: Has Access
description: Whether the subject has any access to the resource
type: object
required:
- subject_type
- subject_type_name
- subject_id
- resource_type
- resource_type_name
- resource_id
- has_access
title: SubjectPermissionResponse
description: Response model for checking a specific subject's permissions on a resource.
GrantPermissionRequest:
properties:
subject_id:
type: string
title: Subject Id
description: ID of the subject (user or team) to grant permission to
examples:
- user-123
- alice@example.com
relation:
type: integer
maximum: 3.0
minimum: 1.0
title: Relation
description: 'Relation type: 1=OWNER, 2=EDITOR, 3=VIEWER'
examples:
- 1
- 2
- 3
resource_type:
type: integer
maximum: 4.0
minimum: 1.0
title: Resource Type
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
examples:
- 1
resource_id:
type: string
title: Resource Id
description: ID of the resource to grant permission on
examples:
- matter-456
subject_type:
type: integer
maximum: 2.0
minimum: 1.0
title: Subject Type
description: 'Subject type: 1=USER, 2=TEAM (default: USER)'
default: 1
examples:
- 1
type: object
required:
- subject_id
- relation
- resource_type
- resource_id
title: GrantPermissionRequest
description: Request model for creating or updating a permission grant.
PermissionMemberResponse:
properties:
subject_type:
type: integer
title: Subject Type
description: 'Subject type: 1=USER, 2=TEAM'
subject_type_name:
type: string
title: Subject Type Name
description: Human-readable subject type name
subject_id:
type: string
title: Subject Id
description: ID of the subject
relation:
type: integer
title: Relation
description: 'Relation type: 1=OWNER, 2=EDITOR, 3=VIEWER'
relation_name:
type: string
title: Relation Name
description: Human-readable relation name
permissions:
items:
type: string
type: array
title: Permissions
description: List of derived permissions (can_view, can_edit, etc.)
created_at:
anyOf:
- type: string
- type: 'null'
title: Created At
description: When the permission was created (ISO format)
created_by:
anyOf:
- type: string
- type: 'null'
title: Created By
description: Who created this permission
type: object
required:
- subject_type
- subject_type_name
- subject_id
- relation
- relation_name
title: PermissionMemberResponse
description: Response model for a single permission/member entry.
InheritedPermissionResponse:
properties:
allowed:
type: boolean
title: Allowed
description: Whether the permission is granted via inheritance
permission:
type: string
title: Permission
description: The permission that was checked
resource_type:
type: integer
title: Resource Type
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
resource_type_name:
type: string
title: Resource Type Name
description: Human-readable resource type name
resource_id:
type: string
title: Resource Id
description: ID of the resource
inherited_via:
anyOf:
- type: string
- type: 'null'
title: Inherited Via
description: How permission was inherited (e.g., 'MATTER' if via Matter-level sharing)
type: object
required:
- allowed
- permission
- resource_type
- resource_type_name
- resource_id
title: InheritedPermissionResponse
description: Response for /permissions/check-inherited - check inherited permission via Matter.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
PermissionCanResponse:
properties:
allowed:
type: boolean
title: Allowed
description: Whether the permission is granted
permission:
type: string
title: Permission
description: The permission that was checked
resource_type:
type: integer
title: Resource Type
description: 'Resource type: 1=MATTER, 2=CONVERSATION, 3=DATASET, 4=DOCUMENT'
resource_type_name:
type: string
title: Resource Type Name
description: Human-readable resource type name
resource_id:
type: string
title: Resource Id
description: ID of the resource
reason:
anyOf:
- type: string
- type: 'null'
title: Reason
description: Reason for access (e.g., 'EDITOR on MATTER:matter-456')
type: object
required:
- allowed
- permission
- resource_type
- resource_type_name
- resource_id
title: PermissionCanResponse
description: Response for /permissions/can - simple boolean permission check.