Capabilities

Projects

Projects are the top-level containers for files, workflows, and agent sessions. These endpoints let you list and search projects, create them, read and update their metadata, and manage who has access.

Project IDs are the same projectId you pass when listing workflows or launching an agent, so listing projects is usually the first call an integration makes.

All paths below are relative to your instance's base URL (https://<your-domain>.nomic.ai/api/v0) and require an API key with the appropriate developer:projects:* scope. See the overview for authentication details.

Scopes

Scope	Grants
`developer:projects:read`	Read projects and their members.
`developer:projects:create`	Create new projects.
`developer:projects:admin`	Update project metadata and member roles.

The broad developer scope implies developer:projects:create and developer:projects:admin (which in turn implies developer:projects:read).

Roles

Members hold one role per project. The member endpoints name roles with the short role values in the first column; the app and the rest of the product use the plain-language names in the second column. They line up one-to-one:

API `role`	In the product	Can
`admin`	Admin	Manage the project, its members, and all of its content.
`editor`	Member	Read and write the project's content — start conversations, and add and edit files.
`viewer`	Read-only member	Read the project's content, but not change it.

Most projects use only Admin and Member (admin and editor) — that is what the app's member picker offers, and what we recommend for integrations. Use viewer (Read-only member) to give someone read-only access to a project they should see but not contribute to.

List projects

GET /projects

List projects available to the authenticated user. For an organization admin this is every project in the organization; for anyone else it is the projects they belong to.

Scope: developer:projects:read · Rate limit: Standard (300 req / min)

Query parameters

Parameter	Type	Default	Description
`limit`	int	`20`	Max results per page (1–100).
`cursor`	string (uuid)	—	Opaque cursor from a previous page's `nextCursor`.
`search`	string	—	Filter by project name or project number (case-insensitive substring).
`membership`	`mine` \| `any`	`any`	`any` returns everything the caller may see; `mine` narrows it to projects the caller belongs to. Identical for non-admins.

Response

{
  "data": [
    {
      "id": "019c587e-3456-7890-abcd-ef1234567890",
      "name": "Downtown Office Tower",
      "description": "Design package reviews and submittals",
      "projectNumber": "2024-0142",
      "createdAt": "2026-04-01T12:00:00.000Z",
      "updatedAt": "2026-08-01T09:30:00.000Z"
    }
  ],
  "nextCursor": null,
  "totalCount": 1
}

Field	Type	Description
`data[].id`	uuid	Project ID — pass as `projectId` on workflows / agents.
`data[].name`	string	Display name.
`data[].description`	string?	Optional description, or `null` if unset.
`data[].projectNumber`	string?	AEC project identifier (project/job number), or `null` if unset.
`data[].createdAt`	string	ISO-8601 creation time.
`data[].updatedAt`	string	ISO-8601 last update time.
`nextCursor`	string?	Opaque cursor for the next page, or `null` if there are no more results.
`totalCount`	number	Total matching projects across all pages.

Errors

Status	Cause
`401`	Missing or invalid API key.
`403`	API key lacks `developer:projects:read` scope.
`429`	Standard rate limit exceeded.

Example

curl "https://<your-domain>.nomic.ai/api/v0/projects?limit=10&search=tower" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

Create a project

POST /projects

Create a project. The authenticated user becomes its first administrator.

Scope: developer:projects:create · Rate limit: Write (60 req / min)

Request body

Field	Type	Required	Description
`name`	string	Yes	Project name (at least one character).
`description`	string	No	Project description.
`projectNumber`	string	No	AEC project identifier (project/job number).

Response

Returns 201 Created with the new project under data.

{
  "data": {
    "id": "019c587e-3456-7890-abcd-ef1234567890",
    "name": "Downtown Office Tower",
    "description": "Design package reviews and submittals",
    "projectNumber": "2024-0142",
    "createdAt": "2026-08-01T09:30:00.000Z",
    "updatedAt": "2026-08-01T09:30:00.000Z"
  }
}

Errors

Status	Cause
`400`	Validation error — e.g. missing `name`.
`401`	Missing or invalid API key.
`403`	API key lacks `developer:projects:create` scope.
`429`	Write rate limit exceeded.

Example

curl -X POST "https://<your-domain>.nomic.ai/api/v0/projects" \
  -H "Authorization: Bearer $NOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown Office Tower",
    "description": "Design package reviews and submittals",
    "projectNumber": "2024-0142"
  }'

Get a project

GET /projects/{id}

Fetch a single project by ID.

Scope: developer:projects:read · Rate limit: Standard (300 req / min)

Path parameters

Parameter	Type	Description
`id`	string (uuid)	Project ID.

Response

{
  "data": {
    "id": "019c587e-3456-7890-abcd-ef1234567890",
    "name": "Downtown Office Tower",
    "description": "Design package reviews and submittals",
    "projectNumber": "2024-0142",
    "createdAt": "2026-04-01T12:00:00.000Z",
    "updatedAt": "2026-08-01T09:30:00.000Z"
  }
}

Errors

Status	Cause
`401`	Missing or invalid API key.
`403`	API key lacks `developer:projects:read` scope.
`404`	No project with that ID is visible to the caller.
`429`	Standard rate limit exceeded.

A project the caller cannot read is reported as 404, so a response never confirms that an ID exists.

Example

curl "https://<your-domain>.nomic.ai/api/v0/projects/019c587e-3456-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

Update a project

POST /projects/{id}

Update a project's metadata. Every field is optional: a field left out is left untouched, and sending null clears a nullable field (description or projectNumber). At least one field must be provided.

Scope: developer:projects:admin · Rate limit: Write (60 req / min)

Path parameters

Parameter	Type	Description
`id`	string (uuid)	Project ID.

Request body

Field	Type	Description
`name`	string	New project name (at least one character).
`description`	string \| null	New description; send `null` to clear it.
`projectNumber`	string \| null	New project/job number; send `null` to clear it.

Response

Returns 200 OK with the updated project under data, in the same shape as Get a project.

Errors

Status	Cause
`400`	Validation error, or no fields to update.
`401`	Missing or invalid API key.
`403`	Read access to the project, but not admin.
`404`	No project with that ID is visible to the caller.
`429`	Write rate limit exceeded.

Example

curl -X POST "https://<your-domain>.nomic.ai/api/v0/projects/019c587e-3456-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer $NOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Updated scope for phase 2", "projectNumber": null }'

List project members

GET /projects/{id}/members

List the members of a project and the role each holds, highest role first.

Scope: developer:projects:read · Rate limit: Standard (300 req / min)

Path parameters

Parameter	Type	Description
`id`	string (uuid)	Project ID.

Query parameters

Parameter	Type	Default	Description
`limit`	int	`50`	Max results per page (1–100).
`cursor`	string	—	Opaque cursor from a previous page's `nextCursor`.

Response

{
  "data": [
    {
      "id": "019abc12-3456-7890-abcd-ef1234567890",
      "email": "alice@example.com",
      "name": "Alice Johnson",
      "image": "https://<your-domain>.nomic.ai/avatars/alice.png",
      "role": "admin"
    }
  ],
  "nextCursor": null,
  "totalCount": 1
}

Field	Type	Description
`data[].id`	uuid	User ID of the member.
`data[].email`	string	Member email.
`data[].name`	string?	Member display name, or `null` if unset.
`data[].image`	string?	Member avatar URL, or `null` if none.
`data[].role`	`admin` \| `editor` \| `viewer`	Role on this project — Admin, Member, or Read-only member (see Roles).
`nextCursor`	string?	Cursor for the next page, or `null` if none remain.
`totalCount`	number	Total members on the project.

Errors

Status	Cause
`401`	Missing or invalid API key.
`403`	API key lacks `developer:projects:read` scope.
`404`	No project with that ID is visible to the caller.
`429`	Standard rate limit exceeded.

Example

curl "https://<your-domain>.nomic.ai/api/v0/projects/019c587e-3456-7890-abcd-ef1234567890/members" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

Update project members

POST /projects/{id}/members

Grant, change, or revoke project roles in one batch of 1–100 changes, applied atomically: nothing is written unless every entry is valid. Set a member's role to null to remove them.

The batch is idempotent — re-stating a role a member already has, or removing a non-member, is a no-op — so a list read from List project members can be sent back unchanged.

Members must already belong to your organization; identify each by user ID or email. Granting access requires project sharing to be enabled on the instance (removals stay available regardless).

Scope: developer:projects:admin · Rate limit: Write (60 req / min)

Path parameters

Parameter	Type	Description
`id`	string (uuid)	Project ID.

Request body

Field	Type	Required	Description
`members`	array	Yes	1–100 member changes to apply as one batch.
`members[].user`	string (uuid or email)	Yes	The member, by user ID or email address.
`members[].role`	`admin` \| `editor` \| `viewer` \| null	Yes	Role to grant — `admin` (Admin), `editor` (Member), or `viewer` (Read-only member) — or `null` to remove the member (see Roles).

Response

Returns 200 OK with the project's members after the batch, highest role first, in the same shape as List project members (without pagination fields).

{
  "data": [
    {
      "id": "019abc12-3456-7890-abcd-ef1234567890",
      "email": "alice@example.com",
      "name": "Alice Johnson",
      "image": null,
      "role": "admin"
    },
    {
      "id": "019abc12-3456-7890-abcd-ef1234567891",
      "email": "bob@example.com",
      "name": "Bob Lee",
      "image": null,
      "role": "editor"
    }
  ]
}

Errors

Status	Cause
`400`	Validation error, or an unknown or repeated user.
`401`	Missing or invalid API key.
`403`	Read access to the project but not admin, or project sharing is disabled.
`404`	No project with that ID is visible to the caller.
`429`	Write rate limit exceeded.

Example

Add Bob as an editor and remove Carol in a single call:

curl -X POST "https://<your-domain>.nomic.ai/api/v0/projects/019c587e-3456-7890-abcd-ef1234567890/members" \
  -H "Authorization: Bearer $NOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      { "user": "bob@example.com", "role": "editor" },
      { "user": "carol@example.com", "role": null }
    ]
  }'

Scopes​

Roles​

List projects​

Query parameters​

Response​

Errors​

Example​

Create a project​

Request body​

Response​

Errors​

Example​

Get a project​

Path parameters​

Response​

Errors​

Example​

Update a project​

Path parameters​

Request body​

Response​

Errors​

Example​

List project members​

Path parameters​

Query parameters​

Response​

Errors​

Example​

Update project members​

Path parameters​

Request body​

Response​

Errors​

Example​

Scopes

Roles

List projects

Query parameters

Response

Errors

Example

Create a project

Request body

Response

Errors

Example

Get a project

Path parameters

Response

Errors

Example

Update a project

Path parameters

Request body

Response

Errors

Example

List project members

Path parameters

Query parameters

Response

Errors

Example

Update project members

Path parameters

Request body

Response

Errors

Example