> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trellistech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Public REST API

> Create, read, update, and delete Trellis tasks and properties with versioned public REST contracts.

The Public REST API gives trusted server-side integrations CRUD access to Trellis tasks and properties. It uses the same workspace API keys created in **Settings > Developer**.

<Note>
  This REST surface is intentionally narrow. Use documented MCP tools for broader Trellis workflows,
  or contact Trellis support before building against objects that are not listed here.
</Note>

## Base URL

```text theme={null}
https://app.trellistech.com/api/v1
```

Interactive reference:

```text theme={null}
https://app.trellistech.com/public-docs
```

OpenAPI document:

```text theme={null}
https://app.trellistech.com/api/v1/openapi.public.json
```

## Authentication

Send the workspace API key as a Bearer token:

```bash theme={null}
curl -H "Authorization: Bearer trls_acmevaca_abc123..." \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/properties?limit=25"
```

The `{workspaceId}` path segment must be the same workspace that issued the key. Workspace IDs are text values, such as `acme-vacations`.

Public REST calls do not require a Trellis web login session or browser cookie. Store API keys only in trusted server-side environments, and rotate a key from **Settings > Developer** if it is exposed.

You can also authenticate with an access token obtained from `POST /api/v1/auth/token`. See [Authentication](/api-reference/authentication) for details.

<Note>
  The linked OpenAPI spec (`openapi.public.json`) documents workspace API key authentication only.
  Session access tokens work at runtime but are not reflected in the generated spec.
</Note>

## Contract versions

| Contract          | Version             | Notes                                                                     |
| ----------------- | ------------------- | ------------------------------------------------------------------------- |
| Public REST API   | `v1`                | Versioned in the URL path                                                 |
| API contract      | `1.4.0`             | Current release                                                           |
| OpenAPI document  | `3.1.0`             | Available at `/api/v1/openapi.public.json`                                |
| Tasks object      | `tasks.v1.3.0`      | Adds daily work orders, cost items, assignees, and expanded filters       |
| Properties object | `properties.v1.2.0` | Removes legacy internal Italian property columns from the public contract |

Breaking changes require a new object contract version or a new REST API version.

## Endpoints

### Properties

| Method          | Path                                                | Description                                  |
| --------------- | --------------------------------------------------- | -------------------------------------------- |
| `GET`           | `/workspaces/{workspaceId}/properties`              | List non-deleted properties in the workspace |
| `POST`          | `/workspaces/{workspaceId}/properties`              | Create a property                            |
| `GET`           | `/workspaces/{workspaceId}/properties/{propertyId}` | Get one property by ID                       |
| `PATCH` / `PUT` | `/workspaces/{workspaceId}/properties/{propertyId}` | Update property fields                       |
| `DELETE`        | `/workspaces/{workspaceId}/properties/{propertyId}` | Soft-delete a property                       |

### Tasks

| Method          | Path                                                | Description                              |
| --------------- | --------------------------------------------------- | ---------------------------------------- |
| `GET`           | `/workspaces/{workspaceId}/tasks`                   | List non-deleted tasks in the workspace  |
| `GET`           | `/workspaces/{workspaceId}/tasks/daily-work-orders` | List daily work orders with cost summary |
| `POST`          | `/workspaces/{workspaceId}/tasks`                   | Create a task                            |
| `GET`           | `/workspaces/{workspaceId}/tasks/{taskId}`          | Get one task by ID                       |
| `PATCH` / `PUT` | `/workspaces/{workspaceId}/tasks/{taskId}`          | Update task fields                       |
| `DELETE`        | `/workspaces/{workspaceId}/tasks/{taskId}`          | Soft-delete a task                       |

## Pagination

List endpoints accept `limit` and `offset`.

| Parameter | Default | Range          |
| --------- | ------- | -------------- |
| `limit`   | `50`    | `1` to `100`   |
| `offset`  | `0`     | `0` or greater |

Responses include:

```json theme={null}
{
  "items": [],
  "pagination": {
    "total": 125,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
```

## Properties

### List properties

```bash theme={null}
curl -H "Authorization: Bearer $TRELLIS_API_KEY" \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/properties?status=ACTIVE&q=duomo"
```

Supported filters:

| Query    | Description                                  |
| -------- | -------------------------------------------- |
| `status` | Property lifecycle status (see values below) |
| `q`      | Search by name, internal code, or city       |
| `limit`  | Maximum number of properties                 |
| `offset` | Number of properties to skip                 |

Property statuses: `PROSPECT`, `ONBOARDING`, `ACTIVE`, `AT_RISK`, `INACTIVE`.

### Get a property

```bash theme={null}
curl -H "Authorization: Bearer $TRELLIS_API_KEY" \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/properties/11111111-1111-4111-8111-111111111111"
```

### Create a property

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $TRELLIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Casa Duomo","status":"ACTIVE","city":"Milano"}' \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/properties"
```

### Update a property

```bash theme={null}
curl -X PATCH \
  -H "Authorization: Bearer $TRELLIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wifiName":"Casa Duomo Guest","checkinTime":"15:00"}' \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/properties/11111111-1111-4111-8111-111111111111"
```

### Delete a property

```bash theme={null}
curl -X DELETE \
  -H "Authorization: Bearer $TRELLIS_API_KEY" \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/properties/11111111-1111-4111-8111-111111111111"
```

### Property object

| Field                   | Type              | Description                               |
| ----------------------- | ----------------- | ----------------------------------------- |
| `id`                    | `uuid`            | Property ID                               |
| `workspaceId`           | `string`          | Workspace that owns the property          |
| `name`                  | `string`          | Display name                              |
| `internalName`          | `string \| null`  | Internal alias                            |
| `internalCode`          | `string \| null`  | Internal code                             |
| `status`                | `string`          | Lifecycle status                          |
| `lifecycleStage`        | `string \| null`  | Fine-grained lifecycle stage              |
| `address`               | `string \| null`  | Street address                            |
| `city`                  | `string \| null`  | City                                      |
| `postalCode`            | `string \| null`  | Postal code                               |
| `country`               | `string \| null`  | Country code                              |
| `latitude`              | `number \| null`  | Latitude                                  |
| `longitude`             | `number \| null`  | Longitude                                 |
| `propertyType`          | `string \| null`  | Property type (e.g. `apartment`, `villa`) |
| `timezone`              | `string \| null`  | IANA timezone (e.g. `Europe/Rome`)        |
| `bedrooms`              | `integer \| null` | Number of bedrooms                        |
| `bathrooms`             | `number \| null`  | Number of bathrooms                       |
| `beds`                  | `integer \| null` | Number of beds                            |
| `maxGuests`             | `integer \| null` | Maximum guest capacity                    |
| `squareMeters`          | `number \| null`  | Floor area in square meters               |
| `floor`                 | `integer \| null` | Floor number                              |
| `hasElevator`           | `boolean`         | Whether the building has an elevator      |
| `hasParking`            | `boolean`         | Whether parking is available              |
| `hasSmartLock`          | `boolean`         | Whether a smart lock is installed         |
| `checkinTime`           | `string \| null`  | Default check-in time                     |
| `checkinTimeEnd`        | `string \| null`  | Check-in window end time                  |
| `checkoutTime`          | `string \| null`  | Default checkout time                     |
| `checkinInstructions`   | `string \| null`  | Check-in instructions                     |
| `checkoutInstructions`  | `string \| null`  | Checkout instructions                     |
| `parkingInstructions`   | `string \| null`  | Parking instructions                      |
| `wifiName`              | `string \| null`  | WiFi network name                         |
| `cleaningFee`           | `number \| null`  | Cleaning fee                              |
| `managementFee`         | `number \| null`  | Management fee                            |
| `cleaningInstructions`  | `string \| null`  | Cleaning instructions                     |
| `propertyLicenseNumber` | `string \| null`  | Property license or registration number   |
| `customFields`          | `object`          | Workspace-specific property fields        |
| `createdAt`             | `datetime`        | Creation timestamp                        |
| `updatedAt`             | `datetime`        | Last update timestamp                     |

Additional room count fields (`kitchens`, `livingRooms`, `hallways`, `terraces`, `balconies`, `gardens`), stay limits (`minNights`, `maxNights`, `minGuests`), and deal tracking (`dealValue`) are also available. See the interactive reference or OpenAPI document for the full schema.

## Tasks

### List tasks

```bash theme={null}
curl -H "Authorization: Bearer $TRELLIS_API_KEY" \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/tasks?status=OPEN&priority=HIGH"
```

Supported filters:

| Query            | Description                                                                  |
| ---------------- | ---------------------------------------------------------------------------- |
| `status`         | Task status (see values below)                                               |
| `priority`       | Task priority (see values below)                                             |
| `propertyId`     | UUID of the related property                                                 |
| `departmentId`   | UUID of the related department                                               |
| `departmentKind` | Filter by department kind (`field_ops`)                                      |
| `scheduledDate`  | Exact scheduled date (`YYYY-MM-DD`); overrides `scheduledFrom`/`scheduledTo` |
| `scheduledFrom`  | Include tasks scheduled on or after this `YYYY-MM-DD` date                   |
| `scheduledTo`    | Include tasks scheduled on or before this `YYYY-MM-DD` date                  |
| `include`        | Comma-separated related resources: `costItems`, `assignees`                  |
| `q`              | Search by title, description, or short ID                                    |
| `limit`          | Maximum number of tasks                                                      |
| `offset`         | Number of tasks to skip                                                      |

Task statuses: `OPEN`, `CREATED`, `DRAFT`, `DRAFTED`, `SCHEDULED`, `IN_PROGRESS`, `FINISHED`, `CLOSED`, `PENDING_APPROVAL`, `REQUEST_APPROVED`, `REQUEST_REJECTED`, `COMPLETED`.

Task priorities: `WATCH`, `LOWEST`, `LOW`, `NORMAL`, `HIGH`, `URGENT`.

Task sources: `MANUAL`, `AUTOMATION`, `SCHEDULE_RULE`, `INTEGRATION`, `AI`, `REVIEW`, `MESSAGE`, `CALL`, `MEETING_BOT`.

### Embedding related resources

Use the `include` query parameter to embed cost items and assignees in the task response:

```bash theme={null}
curl -H "Authorization: Bearer $TRELLIS_API_KEY" \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/tasks?include=costItems,assignees"
```

When included, each task will contain:

* `costItems`: Array of cost line items with `amount`, `currency`, `description`, `billToType`, `categoryName`, and `notes`.
* `assignees`: Array of task assignees with `role` (`PRIMARY` or `SECONDARY`), `type` (`USER` or `VENDOR`), `userId`, `vendorOrgId`, and `name`.

### Get a task

```bash theme={null}
curl -H "Authorization: Bearer $TRELLIS_API_KEY" \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/tasks/22222222-2222-4222-8222-222222222222"
```

### Create a task

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $TRELLIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Replace bathroom light bulb","departmentId":"33333333-3333-4333-8333-333333333333","priority":"HIGH"}' \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/tasks"
```

Task creation uses the same Trellis mutation path as the app: assignees, tags, visit links, activity, notifications, automations, enrichment, and connected operational sync are handled by the normal task side-effect pipeline.

Create request fields:

| Field                      | Type             | Required | Description                                       |
| -------------------------- | ---------------- | -------- | ------------------------------------------------- |
| `title`                    | `string`         | Yes      | Task title                                        |
| `departmentId`             | `uuid`           | Yes      | Department that owns the task                     |
| `description`              | `string \| null` | No       | Task description                                  |
| `propertyId`               | `uuid \| null`   | No       | Related property                                  |
| `propertyName`             | `string`         | No       | Property name (used when `propertyId` is omitted) |
| `priority`                 | `string`         | No       | Task priority                                     |
| `scheduledDate`            | `date`           | No       | Scheduled date (`YYYY-MM-DD`)                     |
| `scheduledTime`            | `time`           | No       | Scheduled time (`HH:MM` or `HH:MM:SS`)            |
| `estimatedDurationMinutes` | `integer`        | No       | Estimated duration in minutes                     |
| `reservationId`            | `uuid \| null`   | No       | Related reservation                               |
| `contactId`                | `uuid \| null`   | No       | Related contact                                   |
| `parentTaskId`             | `uuid \| null`   | No       | Parent task for subtasks                          |
| `templateId`               | `uuid \| null`   | No       | Task template to apply                            |
| `source`                   | `string`         | No       | Task source                                       |
| `isIssue`                  | `boolean`        | No       | Whether this is a reported issue                  |
| `primaryUserId`            | `uuid \| null`   | No       | Primary assigned user                             |
| `primaryVendorOrgId`       | `uuid \| null`   | No       | Primary assigned vendor org                       |
| `secondaryAssigneeIds`     | `uuid[]`         | No       | Additional assignees                              |
| `tagIds`                   | `uuid[]`         | No       | Tag IDs to attach                                 |
| `useDefaultAssignees`      | `boolean`        | No       | Apply default department assignees                |

### Update a task

```bash theme={null}
curl -X PATCH \
  -H "Authorization: Bearer $TRELLIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"COMPLETED","summary":"Bulb replaced and tested."}' \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/tasks/22222222-2222-4222-8222-222222222222"
```

Additional update-only fields: `status`, `summary`, `completedAt`, `startedAt`, `sortOrder`, `projectId`, `billableToOwner`, `cost`, `costCurrency`, `isNoCharge`, `customFields`, `completionFields`, `replacePrimaryUser`.

### Delete a task

```bash theme={null}
curl -X DELETE \
  -H "Authorization: Bearer $TRELLIS_API_KEY" \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/tasks/22222222-2222-4222-8222-222222222222"
```

### Task object

| Field                      | Type               | Description                                                      |
| -------------------------- | ------------------ | ---------------------------------------------------------------- |
| `id`                       | `uuid`             | Task ID                                                          |
| `shortId`                  | `string`           | Human-readable short ID (e.g. `TK-1234`)                         |
| `workspaceId`              | `string`           | Workspace that owns the task                                     |
| `title`                    | `string`           | Task title                                                       |
| `description`              | `string \| null`   | Task description                                                 |
| `status`                   | `string`           | Current status                                                   |
| `priority`                 | `string`           | Priority level                                                   |
| `source`                   | `string`           | How the task was created                                         |
| `departmentId`             | `uuid`             | Owning department                                                |
| `department`               | `object`           | Embedded department with `id`, `name`, `slug`                    |
| `propertyId`               | `uuid \| null`     | Related property                                                 |
| `property`                 | `object \| null`   | Embedded property with `id`, `name`, `status`, `address`, `city` |
| `reservationId`            | `uuid \| null`     | Related reservation                                              |
| `contactId`                | `uuid \| null`     | Related contact                                                  |
| `parentTaskId`             | `uuid \| null`     | Parent task (for subtasks)                                       |
| `scheduledDate`            | `date \| null`     | Scheduled date                                                   |
| `scheduledTime`            | `time \| null`     | Scheduled time                                                   |
| `estimatedDurationMinutes` | `integer \| null`  | Estimated duration in minutes                                    |
| `isIssue`                  | `boolean`          | Whether this is a reported issue                                 |
| `isPublished`              | `boolean`          | Whether the task is published to vendors                         |
| `billableToOwner`          | `boolean`          | Whether billable to the property owner                           |
| `cost`                     | `number \| null`   | Task cost                                                        |
| `costCurrency`             | `string`           | Cost currency code (e.g. `EUR`)                                  |
| `isNoCharge`               | `boolean`          | Whether marked as no charge                                      |
| `summary`                  | `string \| null`   | Completion summary                                               |
| `startedAt`                | `datetime \| null` | When work started                                                |
| `completedAt`              | `datetime \| null` | When the task was completed                                      |
| `customFields`             | `object`           | Workspace-specific task fields                                   |
| `costItems`                | `array`            | Cost line items (when `include=costItems`)                       |
| `assignees`                | `array`            | Task assignees (when `include=assignees`)                        |
| `createdAt`                | `datetime`         | Creation timestamp                                               |
| `updatedAt`                | `datetime`         | Last update timestamp                                            |

Additional fields for integrations, scheduling, vendor workflows, and AI provenance are also returned. See the interactive reference or OpenAPI document for the full schema.

## Daily work orders

The daily work orders endpoint returns tasks with status `SCHEDULED` in field-ops departments for a single calendar date, formatted as costed work orders with assignee details. Use it for daily operations reports and workforce cost summaries. Tasks in other statuses or non-field-ops departments are excluded.

```bash theme={null}
curl -H "Authorization: Bearer $TRELLIS_API_KEY" \
  "https://app.trellistech.com/api/v1/workspaces/acme-vacations/tasks/daily-work-orders?date=2026-06-18"
```

| Query  | Required | Description                                  |
| ------ | -------- | -------------------------------------------- |
| `date` | Yes      | Local calendar date to export (`YYYY-MM-DD`) |

Response:

```json theme={null}
{
  "workspaceId": "acme-vacations",
  "date": "2026-06-18",
  "workOrderCount": 4,
  "totalCost": 148.50,
  "totalCostCurrency": "EUR",
  "costTotalsByCurrency": { "EUR": 148.50 },
  "workOrders": [
    {
      "id": "...",
      "shortId": "TK-1234",
      "title": "Replace bathroom light bulb",
      "description": "Guest reported flickering light.",
      "status": "SCHEDULED",
      "priority": "HIGH",
      "property": { "id": "...", "name": "Casa Duomo", "status": "ACTIVE", "address": "Via Torino 1", "city": "Milano" },
      "department": { "id": "...", "name": "Maintenance", "slug": "maintenance" },
      "scheduledDate": "2026-06-18",
      "scheduledTime": "10:30:00",
      "estimatedDurationMinutes": 45,
      "billableToOwner": false,
      "cost": 35.50,
      "costCurrency": "EUR",
      "isNoCharge": false,
      "costItems": [
        {
          "id": "...",
          "amount": 35.50,
          "currency": "EUR",
          "description": "Replacement bulb and labor",
          "billToType": "COMPANY",
          "categoryName": "Maintenance materials"
        }
      ],
      "assignees": [
        {
          "id": "...",
          "role": "PRIMARY",
          "type": "USER",
          "userId": "...",
          "vendorOrgId": null,
          "name": "Ari Operator"
        }
      ]
    }
  ]
}
```

When tasks use multiple currencies, `totalCost` is `null`, `totalCostCurrency` is `"MIXED"`, and `costTotalsByCurrency` contains per-currency totals.

## Errors

| Status | Meaning                                                                        |
| ------ | ------------------------------------------------------------------------------ |
| `400`  | Request validation failed                                                      |
| `401`  | API key is missing, invalid, expired, or not valid for the requested workspace |
| `403`  | Authenticated user does not have access to the requested workspace             |
| `404`  | Workspace, task, or property was not found                                     |
| `409`  | Task completion is blocked by another task or workflow rule                    |
| `422`  | Request is valid JSON but cannot be applied to the current object              |
| `500`  | Trellis could not complete the request                                         |

## Related articles

* [API Reference](/api-reference/introduction)
* [Authentication](/api-reference/authentication)
* [Trellis MCP Server](/api-reference/mcp-server)
* [Tasks](/platform/tasks)
* [Properties](/platform/properties)