---
title: "Log an implementation note against an intent."
method: POST
path: "/api/v1/intents/{id}/notes"
tags: ["notes"]
---

# Log an implementation note against an intent.

`POST /api/v1/intents/{id}/notes`

Rate-limited by the 'general' bucket (300/h sliding window, keyed user:<userId> or ip:<ip>). The created row's created_by is set to the authenticated userId, but the POST response does NOT echo createdBy (only id, intentId, note, source, createdAt). The GET list response DOES include createdBy.

## Path parameters

- `id` string, required

## Query parameters

- `workspace_id` string

## Request body

- object
  - `note` string, required — Non-empty after trim.
  - `source` 'mcp' | 'cli' | 'github' | 'manual' | 'verification_checkpoint' | 'linear' | 'jira' | 'execution_sync' — Origin of the note; defaults to 'manual' when omitted.

## Response `201`

Created — returns { id, intentId, note, source, createdAt }

- object

## Other responses

- `400` — Invalid request body (zod) — { error, details }; OR cookie-session auth missing workspace_id
- `401` — Invalid/expired API key, or no Bearer key and no valid session cookie
- `403` — Lacks write scope; OR cookie auth not a member of the workspace
- `404` — Intent not found within this workspace
- `429` — Rate limit exceeded (general bucket, 300/h) — { error } with Retry-After header
- `500` — DB error creating note or unexpected internal error

## Changes

- **2026-08-23** `155c812b368b` — 6 info
  - added the optional property `details` to the response with the `400` status
  - added the optional property `details` to the response with the `401` status
  - added the optional property `details` to the response with the `403` status
  - added the optional property `details` to the response with the `404` status
  - …2 more

[Change history](https://skmtc.dev/pathmode/apis/pathmode-api/changes/api/v1/intents/:id/notes/post.md)

---

[API](https://skmtc.dev/pathmode/apis/pathmode-api.md) · [All operations](https://skmtc.dev/pathmode/apis/pathmode-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pathmode/pathmode-api/revisions/e419abb0a327/schema)