Entities

Entities are flexible data objects within projects. Define custom entity types with configurable fields to model your domain.

List Entities

GET /v1/projects/:projectId/entities

Lists entities within a project. The project is identified by the URL path.

Query Parameters

Create Entity

POST /v1/projects/:projectId/entities

The project is taken from the URL path; it is not sent in the body. System-assigned fields (id, org_id, created_at, updated_at) are never supplied by the caller: the organization comes from the authenticated session and the rest are assigned by the server.

Request Body

{
  "entity_type_id": "...",
  "name": "My Entity",
  "data": {
    "custom_field": "value"
  }
}

Response

On success (201 Created) the complete created entity is returned.

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "project_id": "...",
    "parent_id": null,
    "title": "My Entity",
    "type_uuid": "...",
    "metadata": {
      "custom_field": "value"
    },
    "state_uuid": null,
    "sort_order": 0,
    "owner_scope": "org",
    "owner_id": null,
    "is_active": true,
    "created_by_user_id": "...",
    "created_at": "2026-06-20T12:00:00Z",
    "updated_at": "2026-06-20T12:00:00Z"
  }
}

Response Codes

Get Entity

GET /v1/entities/:entityId

Update Entity

PUT /v1/entities/:entityId

Delete Entity

DELETE /v1/entities/:entityId

Entity Types

Entity types define the schema for entities: what fields they have, validation rules, and display configuration.

List Entity Types

GET /v1/entity-types?project_id=...

Create Entity Type

POST /v1/entity-types

Entity types are organization-scoped; the owning organization comes from the authenticated session. System-assigned fields (id, org_id, version, created_at, updated_at) are never supplied by the caller; they are assigned by the server.

Request Body

{
  "name": "Bug Report",
  "fields": [
    {
      "name": "severity",
      "type": "select",
      "options": ["low", "medium", "high", "critical"]
    },
    {
      "name": "description",
      "type": "text"
    }
  ]
}

Response

On success (201 Created) the complete created entity type is returned.

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "display_name": "Bug Report",
    "description": null,
    "icon": null,
    "color": null,
    "parent_uuid": null,
    "category": null,
    "fields": [ /* the supplied field definitions */ ],
    "ai_instructions": {},
    "relationship_mode": "open",
    "owner_scope": "org",
    "owner_id": null,
    "default_entity_owner_scope": "org",
    "permission_flags": {},
    "version": 1,
    "is_active": true,
    "created_by_user_id": "...",
    "created_at": "2026-06-20T12:00:00Z",
    "updated_at": "2026-06-20T12:00:00Z"
  }
}

Response Codes

Relationships

Define relationships between entities: one-to-many, many-to-many, or typed relationships with custom metadata.

List Relationships

GET /v1/relationships?entity_id=...

Create Relationship

POST /v1/relationships

System-assigned fields (id, org_id, created_at, updated_at) are never supplied by the caller; the organization comes from the authenticated session and the rest are assigned by the server.

Request Body

{
  "source_entity_id": "...",
  "target_entity_id": "...",
  "relationship_type_id": "..."
}

relationship_type_id references a relationship type (see POST /v1/relationship-types); source and target must differ.

Response

On success (201 Created) the complete created relationship is returned.

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "source_entity_id": "...",
    "target_entity_id": "...",
    "relationship_type_id": "...",
    "is_active": true,
    "created_by_user_id": "...",
    "created_at": "2026-06-20T12:00:00Z",
    "updated_at": "2026-06-20T12:00:00Z"
  }
}

Response Codes