Field API Reference

Field

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`DELETE`

List all field notes

Create, read, update, and resolve toolbar field notes — UI feedback a user points at on their own site, surfaced to coding agents over MCP.

Required API key scopes

field_note:read

Query parameters

field_note_status
string
One of: "acknowledged""dismissed""pending""resolved"
host
string
limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/field_notes
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/field_notes/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/field_notes/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "comment": "string",
      "field_note_status": "pending",
      "resolution": "string",
      "url": "string",
      "host": "string",
      "pathname": "string",
      "selector": "string",
      "element_text": "string",
      "element_chain": "string",
      "element_context": {},
      "viewport": {
        "width": 0,
        "height": 0
      },
      "screenshot_url": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      }
    }
  ]
}

Create field notes

Create, read, update, and resolve toolbar field notes — UI feedback a user points at on their own site, surfaced to coding agents over MCP.

Required API key scopes

field_note:write

Request parameters

comment
string
field_note_status
resolution
stringnull
url
string
host
string
pathname
stringnull
selector
string
element_text
stringnull
element_chain
stringnull
element_context
object
viewport
objectnull
screenshot_url
stringnull

Response

Example request

POST /api/projects/:project_id/field_notes
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/field_notes/\
	-d comment="string",\
	-d url="string",\
	-d host="string",\
	-d selector="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/field_notes/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"comment": "string",
		"url": "string",
		"host": "string",
		"selector": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "comment": "string",
  "field_note_status": "pending",
  "resolution": "string",
  "url": "string",
  "host": "string",
  "pathname": "string",
  "selector": "string",
  "element_text": "string",
  "element_chain": "string",
  "element_context": {},
  "viewport": {
    "width": 0,
    "height": 0
  },
  "screenshot_url": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  }
}

Retrieve field notes

Create, read, update, and resolve toolbar field notes — UI feedback a user points at on their own site, surfaced to coding agents over MCP.

Required API key scopes

field_note:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/field_notes/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/field_notes/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/field_notes/{field_note_id}/".format(
        project_id=project_id,
		field_note_id="<the field note id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "comment": "string",
  "field_note_status": "pending",
  "resolution": "string",
  "url": "string",
  "host": "string",
  "pathname": "string",
  "selector": "string",
  "element_text": "string",
  "element_chain": "string",
  "element_context": {},
  "viewport": {
    "width": 0,
    "height": 0
  },
  "screenshot_url": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  }
}

Update field notes

Create, read, update, and resolve toolbar field notes — UI feedback a user points at on their own site, surfaced to coding agents over MCP.

Required API key scopes

field_note:write

Path parameters

id
string

Request parameters

comment
string
field_note_status
resolution
stringnull
url
string
host
string
pathname
stringnull
selector
string
element_text
stringnull
element_chain
stringnull
element_context
object
viewport
objectnull
screenshot_url
stringnull

Response

Example request

PATCH /api/projects/:project_id/field_notes/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/field_notes/:id/\
	-d comment="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/field_notes/{field_note_id}/".format(
        project_id=project_id,
		field_note_id="<the field note id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"comment": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "comment": "string",
  "field_note_status": "pending",
  "resolution": "string",
  "url": "string",
  "host": "string",
  "pathname": "string",
  "selector": "string",
  "element_text": "string",
  "element_chain": "string",
  "element_context": {},
  "viewport": {
    "width": 0,
    "height": 0
  },
  "screenshot_url": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  }
}

Delete field notes

Create, read, update, and resolve toolbar field notes — UI feedback a user points at on their own site, surfaced to coding agents over MCP.

Required API key scopes

field_note:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/field_notes/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/field_notes/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/field_notes/{field_note_id}/".format(
        project_id=project_id,
		field_note_id="<the field note id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Field

Endpoints

List all field notes

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Create field notes

Required API key scopes

Request parameters

Response

Example request

Example response

Status 201

Retrieve field notes

Required API key scopes

Path parameters

Response

Example request

Example response

Status 200

Update field notes

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Delete field notes

Required API key scopes

Path parameters

Example request

Example response

Status 204 No response body

Community questions