Skip to content

Routes, payloads, and errors

Fields, responses, and errors for the task, post, and comment routes, and how retries behave.

Routes and payloads

Send a JSON object to one of three routes on https://projectfeed.app. Every request is signed as described in Signing and security. The request body can be up to 256 KiB. A larger body returns 413.

POST /api/v1/webhooks/inbound/tasks

Create a task, or update the task with the same source and externalId.

sourcestringrequired
Short name of the sending system, such as github or ci.
externalIdstringrequired
The sender's stable ID for this item.
titlestringrequired
Task title. Longer than 200 characters is cut to 200.
projectIdstring
Project to create the task in. Required for a secret that covers all projects. A project secret uses its own project and rejects a different projectId.
descriptionstring
Plain text description.
statusstring
backlog, todo, in_progress, perpetual, in_review, done, or cancelled. New tasks default to backlog.
prioritystring
none, low, medium, high, or urgent. New tasks default to none.
assigneeEmailstring
Email of a workspace member to assign. An email that matches no active member is ignored.
dueDatenumber
Due date as a Unix timestamp in milliseconds.
JSON
{
  "source": "ci",
  "externalId": "build-1234",
  "projectId": "prj_abc123",
  "title": "Flaky CI on main",
  "description": "Tests intermittently fail on the auth suite.",
  "status": "todo",
  "priority": "high",
  "assigneeEmail": "alex@example.com"
}

Returns 201 when the item is new and 200 when it updates an existing item. The status field in the response is created or updated.

JSON
{
  "taskId": "tsk_abc123",
  "identifier": "WEB-42",
  "status": "created"
}

identifier is null when the project has no identifier prefix. An update changes only the fields you send. It always sets the title.

POST /api/v1/webhooks/inbound/posts

Create a post, or update the post with the same source and externalId.

sourcestringrequired
Short name of the sending system.
externalIdstringrequired
The sender's stable ID for this post.
titlestringrequired
Post title. Longer than 500 characters is cut to 500.
projectIdstring
Project to create the post in. Required for a secret that covers all projects.
contentstring | object
Post body as plain text or rich text JSON. Empty when omitted and contentHtml is also omitted.
contentHtmlstring
Plain text body, used only when content is omitted. Markup is not rendered.
statusstring
draft or published. New posts default to draft.
JSON
{
  "source": "perforce",
  "externalId": "change-10421",
  "title": "alex submitted changelist 10421",
  "content": "Updated lighting and fixed the build.",
  "status": "published"
}

Returns 201 when the item is new and 200 when it updates an existing item. The status field in the response is created or updated.

JSON
{
  "postId": "pst_abc123",
  "identifier": "REL-18",
  "status": "created"
}

Changing the text of an existing post saves a new version. Sending published for a draft publishes it.

POST /api/v1/webhooks/inbound/comments

Add a comment to a post that an earlier request created, or update the comment with the same source and externalId.

sourcestringrequired
Short name of the sending system.
externalIdstringrequired
The sender's stable ID for this comment.
externalParentSourcestringrequired
The source of the post this comment belongs to.
externalParentIdstringrequired
The externalId of that post. The post must already exist. Send it to the posts route first.
contentstring | objectrequired
Comment body as plain text or rich text JSON. It cannot be empty and is limited to 128 KB.
JSON
{
  "source": "ci",
  "externalId": "build-1234-note-1",
  "externalParentSource": "perforce",
  "externalParentId": "change-10421",
  "content": "Build passed on all platforms."
}

Returns 201 when the item is new and 200 when it updates an existing item. The status field in the response is created or updated.

JSON
{
  "commentId": "cmt_abc123",
  "postId": "pst_abc123",
  "status": "created"
}

Comments attach to posts only. If no post matches the parent source and ID, the route returns 404. A secret for one project only finds parents in that project.

Each secret can send up to 1,000 requests a minute. Going over returns 429 with a Retry-After header. See rate limits.

Retries and duplicates

Project Feed treats source and externalId as the identity of an item within the workspace. The first request creates it. Later requests with the same pair update it, so a retry with a new signature never makes a duplicate. If the pair already belongs to an item in another project, the request returns 409.

Project Feed also rejects a request whose signature it has already accepted. If you retry the exact same signed request, you get 409 with the detail Duplicate request, which means the first attempt worked. To send the same item again, sign a new request with a fresh timestamp.

Errors

400
The body is not a JSON object, a required field is missing, or projectId is missing or does not match the secret's project.
401
A signature header is missing, the secret is unknown or revoked, the signature does not match, or the timestamp is more than 5 minutes from the server clock.
404
The project does not exist in this workspace, or the parent post for a comment was not found.
409
Duplicate request, or the source and externalId belong to an item in another project.
413
The body is larger than 256 KiB.
429
The secret went over 1,000 requests a minute.

Error bodies follow the format in API errors.

Image preview
100%