list_ai_projects

ArtificialIntelligenceApi.list_ai_projects(role_id, type=None, limit=None, offset=None, sortorder=None, sortby=None, projection_expression=None, filter_expression=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

List AI projects

Returns the AI projects you can access. Super-admins see every project and are treated as owners. Pinned projects are returned separately in pinnedProjects, in the order user pinned them, and are not included in projects. Each response also includes recentThreads, a combined list of recent threads across those projects. Pass type=categories to list categories instead of projects. That response returns only Categories — each category name and how many projects use it — and ignores paging, sorting, filtering, and field projection. Projects with no category are not included.

Parameters:

  • role_id (str) – Amorphic role used to authorize this request. (required)

  • type (str) – Set to categories to return category names and project counts instead of the project list. Omit this parameter to list projects.

  • limit (int) – Maximum number of projects to return per page. Defaults to 100. Values above 1000 are rejected. Does not apply to pinned projects, recent threads, or category listing.

  • offset (int) – 1-based index of the first unpinned project to return. Defaults to 1. Pinning or unpinning a project can change which items appear on a given page. Ignored when listing categories.

  • sortorder (str) – Sort direction for the project list. Defaults to desc. Ignored when listing categories.

  • sortby (str) – Field to sort the project list by. Defaults to LastModifiedTime. Choose a string field that is present on every project. Ignored when listing categories.

  • projection_expression (str) – Comma-separated list of project fields to return, for example ProjectId,ProjectName,ProjectStatus. Applies to the project list and pinned projects, not to recent threads. Unknown field names are ignored. Ignored when listing categories.

  • filter_expression (str) – Filter applied to the project list before sorting and paging. Use comma-separated Key:Value pairs, for example Category:Legal Multiple pairs are combined with OR. ProjectName and Keywords accept * as a case-insensitive wildcard; other fields match exactly, ignoring case. Use true or false for booleans, and null for a missing value. Pinned projects are never filtered. Ignored when listing categories.

  • _request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.

  • _request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.

  • _content_type (str, Optional) – force content-type for the request.

  • _headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.

  • _host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

ListProjectsResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: GET /ai/projects

Success (HTTP 200)

Project list, or category list when type=categories. Page through `projects` by increasing `offset` by `limit` while `next_available` is the string “yes”. Stop when it is “no”. `next_available` is a string, not a boolean. `total_count` is the number of matching unpinned projects; `count` is how many are on this page. `pinnedProjects` and `recentThreads` are returned in full on every page.

First page of projects, with one pinned project

{
  "projects": [
    {
      "ProjectId": "3f1b8d24-9c76-4e0a-b52f-8d41a7c6e903",
      "ProjectName": "Vendor Risk Review",
      "ProjectStatus": "configured",
      "Description": "Vendor questionnaires and risk scoring",
      "Keywords": [
        "vendors",
        "risk"
      ],
      "Category": "Legal",
      "EnforceResourceACLs": false,
      "SmartChunking": false,
      "AccessType": "read-only",
      "CreationTime": "2026-05-02 09:14:07",
      "CreatedBy": "jsmith",
      "LastModifiedTime": "2026-06-18 11:42:55",
      "LastModifiedBy": "jsmith"
    }
  ],
  "pinnedProjects": [
    {
      "ProjectId": "7c9e6f3a-2b41-4d8e-9a15-6f0c2d5b8e41",
      "ProjectName": "Contracts Assistant",
      "ProjectStatus": "configured",
      "Description": "Answers questions over the contract archive",
      "Keywords": [
        "contracts",
        "legal"
      ],
      "Category": "Legal",
      "EnforceResourceACLs": true,
      "SmartChunking": true,
      "AccessType": "owner",
      "CreationTime": "2026-04-11 15:02:33",
      "CreatedBy": "apatel",
      "LastModifiedTime": "2026-06-20 08:31:10",
      "LastModifiedBy": "apatel"
    }
  ],
  "recentThreads": [
    {
      "ThreadId": "d4c81f27-6b93-4a05-9e18-7c2f5a0d6b34",
      "Title": "Renewal clause in the Acme MSA",
      "LastModifiedTime": "2026-06-20 08:30:52",
      "CreatedBy": "apatel",
      "Visibility": "private",
      "ProjectId": "7c9e6f3a-2b41-4d8e-9a15-6f0c2d5b8e41",
      "ProjectName": "Contracts Assistant"
    }
  ],
  "count": 1,
  "total_count": 1,
  "next_available": "no"
}

Categories and how many projects use each

{
  "Categories": [
    {
      "Category": "Legal",
      "ProjectCount": 4
    },
    {
      "Category": "Support",
      "ProjectCount": 1
    }
  ]
}

Errors

Documented error codes: AUTH-1001, AUTH-1030, IPV-1045, IPV-1004, GE-1008.

HTTP 400

The request was invalid or you do not have permission. The body is {“Message”: “<CODE> - <text>”}. Common cases include a missing role_id (AUTH-1001), missing ai.view permission (AUTH-1030), a limit above 1000 (IPV-1045), or a malformed filterExpression (IPV-1004). Permission failures return 400, not 403.

limitTooHigh

{
  "Message": "IPV-1045 - Invalid parameter - 5000, value either missing or is invalid."
}

missingPermission

{
  "Message": "AUTH-1030 - User is not authorized to list all projects due to the following missing permission(s) - {'Ai': ['view']}"
}

HTTP 500

An unexpected server error. The body is typically {“Message”: “GE-1008 - Could not complete the request. Please try again.”}. This can also occur if sortby names a missing or non-string field.

Request / response example

{
  "Message": "GE-1008 - Could not complete the request. Please try again."
}