*MCP › Reference › Rentals › Projects*

# Update a project

> Changes the record of a project: name, dates, customer, type, external reference, location and color (send only the fields to change).

It does NOT change the status, the archiving or the linked orders: links have their own sub-resource. An archived project is read-only: the request is rejected with 409 `conflict` and nothing is written; unarchive it first with [`PUT /api/v1/projects/{projectId}/archive`](https://docs.filmo.io/rest-api/endpoint-reference/projects/archive-or-restore-a-project) and `archived: false`. The customer and the project type are checked against the account of the API key before writing anything. Returns the full project, the same projection as its GET.

TOOL `filmo_projects_update` · `projects:write` · 120/min · Server annotation: Idempotent

## Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | Project identifier. |
| `name` | string | No | Project name. At least three characters, as the domain requires. |
| `startDate` | string<date-time> | No | Project start (ISO 8601 with offset). |
| `endDate` | string<date-time> | No | Project end (ISO 8601 with offset). It cannot be earlier than startDate; the same instant is a one-day project. |
| `contactId` | string | No | Project customer. It must belong to the account of the API key. |
| `projectTypeId` | string | No | Project type; resolve it against `/api/v1/project-types`. null clears it. |
| `externalReference` | string | No | Free-form reference to match the project with an external system; null clears it. |
| `location` | object | No | Physical location of the project (a stage, a client site). Only the fields sent are recorded. |
| `location.name` | string | No | Name of the place, for example "Main stage". |
| `location.address` | string | No | Street address. |
| `location.city` | string | No | City. |
| `location.postalCode` | string | No | Postal code. |
| `location.province` | string | No | Province or region. |
| `location.country` | string | No | Country. |
| `location.lat` | number | No | Latitude in decimal degrees. |
| `location.lng` | number | No | Longitude in decimal degrees. |
| `color` | string | No | Color of the project card (for example "#3b82f6"); null clears it. |
| `idempotencyKey` | string | No | Idempotency key chosen by the client (a UUID is recommended). Repeating the same key with the same arguments within 24 h returns the stored response without executing again; with different arguments it responds 422. It is the safe way to retry after a network failure. |
| `ifMatch` | string | No | Optimistic locking: the meta.etag you got from the detail read of this resource (or "*"). If the resource changed since, the call fails with 412 precondition_failed before writing anything; read it again and retry. Omit it to write unconditionally. |

## Result

On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`.

| Name | Type | Description |
| --- | --- | --- |
| `id` | string | Unique project identifier. |
| `projectNumber` | string | Human-readable project number; null if not numbered. |
| `name` | string | Project name. |
| `color` | string | Color associated with the project (for the UI); null if none. |
| `externalReference` | string | External reference of the project (for example, from the customer system); null if not recorded. |
| `projectTypeId` | string | Project type identifier; null if the project has no type. |
| `projectType` | object | Compact reference to the project type; null if none. |
| `projectType.id` | string | Unique project type identifier. |
| `projectType.name` | string | Project type name. |
| `projectType.color` | string | Color associated with the project type (for the UI); null if none. |
| `contact` | object | Compact reference to the project contact; null if none. |
| `contact.id` | string | Unique contact identifier. |
| `contact.name` | string | Contact name. |
| `location` | object | Project location; its inner fields are null when not recorded. |
| `location.name` | string | Name of the place/location; null if not recorded. |
| `location.address` | string | Address of the location; null if not recorded. |
| `location.city` | string | City of the location; null if not recorded. |
| `location.postalCode` | string | Postal code of the location; null if not recorded. |
| `location.province` | string | Province or region of the location; null if not recorded. |
| `location.country` | string | Country of the location; null if not recorded. |
| `location.lat` | number | Latitude of the location; null if not recorded. |
| `location.lng` | number | Longitude of the location; null if not recorded. |
| `startDate` | string<date-time> | Project start date in ISO 8601 with offset. |
| `endDate` | string<date-time> | Project end date in ISO 8601 with offset. |
| `status` | string | Project status: draft, budgeted, confirmed, in_progress, invoiced, completed, cancelled or archived. `archived` is a LEGACY status that appears in old data; the current archived state is expressed by the `archived` boolean of this same DTO. `draft`, `budgeted`, `confirmed`, `in_progress`, `invoiced`, `completed`, `cancelled`, `archived` |
| `archived` | boolean | Whether the project is archived. |
| `orderIds` | string[] | Identifiers of the project orders. Order details are obtained from [`GET /api/v1/orders`](https://docs.filmo.io/rest-api/endpoint-reference/orders/list-orders)?projectId=. |
| `totalOrders` | integer | Total number of orders in the project (equals orderIds.length). |
| `tags` | object[] | Tags attached to the project, with their identifier and name. |
| `tags.id` | string | Unique identifier of the tag. |
| `tags.name` | string | Tag name. |
| `customFields` | object<string, any> | Custom field values by custom field identifier; the definitions are in `/api/v1/custom-fields`. |
| `source` | string | Source the project was created from; null if not recorded. |
| `createdAt` | string<date-time> | Creation date in ISO 8601 with offset. |
| `updatedAt` | string<date-time> | Last update date in ISO 8601 with offset. |

*Call · filmo_projects_update*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_projects_update",
    "arguments": {
      "projectId": "proj_8f2a1c"
    }
  }
}
```

*Result (generated from the schema)*

```json
{
  "structuredContent": {
    "data": {
      "id": "id_8f2a1c",
      "projectNumber": "<projectNumber>",
      "name": "Example",
      "color": "<color>",
      "externalReference": "<externalReference>",
      "projectTypeId": "proj_8f2a1c",
      "projectType": {
        "id": "id_8f2a1c",
        "name": "Example",
        "color": "<color>"
      },
      "contact": {
        "id": "id_8f2a1c",
        "name": "Example"
      },
      "location": {
        "name": "Example",
        "address": "<address>",
        "city": "<city>",
        "postalCode": "<postalCode>",
        "province": "<province>",
        "country": "ES",
        "lat": 1,
        "lng": 1
      },
      "startDate": "2026-09-01T08:00:00Z",
      "endDate": "2026-09-01T08:00:00Z",
      "status": "draft",
      "archived": true,
      "orderIds": [
        "orde_8f2a1c"
      ],
      "totalOrders": 1,
      "tags": [
        {
          "id": "id_8f2a1c",
          "name": "Example"
        }
      ],
      "customFields": {
        "key": "<key>"
      },
      "source": "<source>",
      "createdAt": "2026-09-01T08:00:00Z",
      "updatedAt": "2026-09-01T08:00:00Z"
    },
    "meta": {
      "idempotencyKey": "<the key you sent, or the one the server generated>",
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## The same operation by REST

This tool runs [`PATCH /api/v1/projects/{projectId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/update-a-project).

---

Canonical URL: https://docs.filmo.io/mcp/tools/projects/filmo-projects-update  
Last updated: 2026-10-25