REST API Access Guide

1. What's included

Every workspace can issue a one-time API access key to call ResourcePlanner's built-in REST endpoints directly. The key authenticates requests to the same server-side routes that power the web application, so you always receive normalized JSON responses.

2. Generating the API access key

1. Sign in and open Settings → API access for REST clients.
2. Click Generate new key.
3. Copy the one-time value that appears in the dialog. The plaintext key is never shown again.
4. Store it securely (we recommend a secrets manager). You can revoke or regenerate the key at any time from the same screen.

Only one API access key can exist per workspace. Regenerating a key immediately invalidates the previous value.

3. Authentication

All API requests must include the key in the Authorization header using the Bearer scheme:

curl https://resourceplanner.io/api/resources \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>"

• The key encodes your workspace ID, so every request is scoped to your workspace automatically.
• Keys are currently unlimited; apply your own rate limiting if you expose the key to client-side apps.

4. Supported endpoints

The following endpoints accept bearer authentication. Payloads use camelCase fields, and responses always return the normalized ResourcePlanner shape.

| Method | Endpoint | Notes |
| ------ | -------- | ----- |
| GET | `/api/resources` | List all resources in the workspace. |
| POST | `/api/resources` | Create a new resource. |
| PUT | `/api/resources/{id}` | Update a resource (partial updates supported). |
| DELETE | `/api/resources/{id}` | Delete a resource and its assignments. |
| GET | `/api/projects` | List all projects. |
| POST | `/api/projects` | Create a project; accepts optional `projectSize` (hours), `projectRate`, and `resourceRates[]`. |
| PUT | `/api/projects/{id}` | Update a project; set `projectSize`, `projectRate`, or `resourceRates[]` (use `null` or an empty array to clear). |
| DELETE | `/api/projects/{id}` | Delete a project and its assignments. |
| GET | `/api/assignments` | Optional filters: `projectId`, `resourceId`, `dateFrom`, `dateTo`. |
| POST | `/api/assignments` | Create an assignment using camelCase payloads; optional task fields are supported. |
| PUT | `/api/assignments/{id}` | Update date range, hours, note, links, or task details. |
| DELETE | `/api/assignments/{id}` | Remove an assignment. |

Filtering assignments

GET /api/assignments accepts optional projectId, resourceId, dateFrom, and dateTo query parameters to refine the list. Provide just one date to fetch everything after or before that point, or pass both to limit results to a specific window. Aliases from and to work as shorthand. When no filters are provided, you receive every assignment in the workspace.

5. Creating data

Write endpoints accept the same payloads the web app uses internally. The examples below demonstrate how to create each entity with typical fields.

Create a resource

curl -X POST https://resourceplanner.io/api/resources \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Jordan Weaver",
        "email": "jordan.weaver@example.com",
        "invited": true,
        "membership": {
          "role": "manager",
          "memberSettings": { "visibility": "team" },
          "managerSettings": {
            "scope": "managed",
            "managesResources": ["RESOURCE_ID"],
            "canSeeFinancials": true
          }
        },
        "capacity": 37.5,
        "hourlyExpense": 45,
        "workDays": [1, 2, 3, 4, 5]
      }'

Supply access settings inside the nested membership object. Set invited=true to trigger an email invitation. The server sanitises the payload before persisting.

To add someone without inviting them yet, omit invited (or set it to false) and skip the membership block—the resource will be created without any access assigned.

Valid roles are member, manager, admin, and customer. The server applies safe defaults—for example, admins automatically gain full financial access.

• memberSettings.visibility: self restricts the person to their own calendar; team lets them view teammates they are allowed to manage.
• managerSettings.scope: use managed to constrain actions to the managesResources array, orall for workspace-wide control.
• managerSettings.managesAllMembers: set true to grant access to every resource without listing IDs. When false, populate managesResourceswith resource IDs the manager oversees.
• managerSettings.canSeeFinancials: trueexposes project rates (including overrides) and resource expenses; managers who lack this flag will have those fields removed from responses.
• customerSettings.projectIds: array of project IDs the customer can view or edit.
• customerSettings.canEditAssignments: allow customers to create or modify assignments within their project list.
• status: optional lifecycle state—pending,active, inactive, or declined.

Responses include the normalised membership snapshot (role, status, settings) so you can confirm what was persisted.

Create a project

curl -X POST https://resourceplanner.io/api/projects \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Website Relaunch",
        "color": "#2563eb",
        "note": "Public roadmap initiative",
        "projectSize": 240,
        "projectRate": 125,
        "resourceRates": [
          { "resourceId": "RESOURCE_ID", "rate": 150 }
        ]
      }'

Include the optional projectSize field to capture the estimated total hours for the project. Send a non-negative number to set it or null to clear existing values.

When you need to manage billing, set projectRate for the default hourly amount and include a resourceRates array with objects like { "resourceId": "RES_ID", "rate": 150 }for overrides. Each resource can have only one override, and these values are only readable by users with financial permissions.

Create an assignment

curl -X POST https://resourceplanner.io/api/assignments \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "project": "PROJECT_ID",
        "resource": "RESOURCE_ID",
        "dateFrom": "2025-10-20",
        "dateTo": "2025-10-24",
        "hoursPerDay": 6,
        "note": "Internal workshop prep",
        "title": "Prepare workshop materials",
        "description": "<p>Collect slides, examples, and handouts.</p>"
      }'

Tasks are represented as optional metadata on assignments. There is no separate public /api/tasks endpoint. Send title to create or update the assignment's linked task, and include description or comments when you need richer task detail. Leave title empty or omit it for a plain assignment.

| Field | Used on | Notes |
| ----- | ------- | ----- |
| `title` | request/response | Optional task title. A non-empty value creates or updates the linked task for the assignment. |
| `description` | request/response | Optional rich-text HTML task description. |
| `comments` | request/response | Optional task comments array; each comment should include at least `body`. |
| `taskId` | response only | ID of the linked task, or `null` when the assignment has no task. |
| `task` | response only | Expanded task object with `id`, `title`, `description`, and `comments`. |