Create a project link

POSThttps://<your-url>/api/v2/project-links

MCP id project-links.storeAlso on this path: GET List project links

Pins a named URL to the project named in the body and returns it with a Location header.

Token scope: api:write:projects
Without it: 403 insufficient-token-scope.
Permission: projects::links
Without it: 403 insufficient-permission.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts Idempotency-Key. Never cached: private, no-store. Unknown body keys are refused, never dropped.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: Pin a staging environment

curl -X POST \
  'https://<your-url>/api/v2/project-links' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "project_id": 1,
    "name": "Staging",
    "url": "https://staging.example.test"
  }'

const response = await fetch('https://<your-url>/api/v2/project-links', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "project_id": 1,
    "name": "Staging",
    "url": "https://staging.example.test"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/project-links', [
        'project_id' => 1,
        'name' => 'Staging',
        'url' => 'https://staging.example.test',
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/project-links',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'project_id': 1, 'name': 'Staging', 'url': 'https://staging.example.test'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "project_id": 1,
    "project": {
      "id": 1
    },
    "name": "Staging",
    "url": "https://staging.example.test",
    "created_at": "2026-03-04T09:15:00Z",
    "updated_at": "2026-03-04T09:15:00Z",
    "links": {
      "self": "https://<your-url>/api/v2/work-items/1"
    }
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/idempotency-key-in-flight",
  "title": "Idempotency key in flight",
  "status": 409,
  "detail": "The original request for this Idempotency-Key is still being processed. Retry shortly.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S"
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 fields failed validation.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "errors": [
    {
      "pointer": "/date",
      "code": "date_format",
      "detail": "The date does not match the format Y-m-d."
    },
    {
      "pointer": "/minutes",
      "code": "min",
      "detail": "The minutes must be at least 1."
    },
    {
      "pointer": "/description",
      "code": "required",
      "detail": "The description field is required."
    }
  ]
}

project_id, name and url are all required, and a link cannot be created against a soft-deleted project. The write also bumps the owning project's updated_at, so the project's ETag changes and it reappears in an incremental filter[updated_at][gte] window, and it is recorded in the project's activity timeline rather than a timeline of its own. Every project link operation requires the projects::links permission, not the projects prefix's usual create, read, update and delete permissions.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

Idempotency-Keystring≤ 255

A caller-chosen key that makes this POST safe to retry. Replaying it returns the original response with Idempotency-Replayed: true.

Request body

Unknown keys are refused with 422, naming the key.

project_idinteger → Project.idRequired

Owning project.

namestring≤ 255Required

Link name as shown in the UI, e.g. Staging. This is the default sort key.

urlurlRequired

The link target, e.g. https://staging.example.test.

Response 201

Returns a ProjectLink in the detail view.

Headers

ETag: A strong validator of exactly this representation.
Idempotency-Replayed: true when this response was replayed from a stored Idempotency-Key rather than produced by a new write.
Location: The absolute URL of the created or queued resource.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning