> Markdown version of https://authpi.com/docs/reference/core-api/notes/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Notes — AuthPI Core API

Admin/team notes management. Notes can be attached to resources (users, organizations, issuers, clients) for internal documentation. Supports @mentions of team members and [[references]] to other resources.

## GET /v1/accounts/{account_id}/notes

**List Notes**

Lists admin/team notes for an account with optional filtering.

Notes can be filtered by:
- **subject_type** and **subject_id** - Notes attached to a specific resource
- **issuer_id** - Notes within a specific issuer (required for user/org notes)
- **created_by** - Notes created by a specific team member
- **pinned** - Only pinned or unpinned notes
- **mentions_user_id** - Notes that @mention a specific team member

Results are ordered by pinned status (pinned first) then by creation date (newest first).

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Pagination cursor (format: pinned:timestamp) |
| `subject_type` | object | Optional | Filter by subject type (user, org, issuer, client) |
| `subject_id` | string | Optional | Filter by subject ID (requires subject_type) |
| `issuer_id` | string | Optional | Filter by issuer ID (required for user/org subjects) |
| `created_by` | string | Optional | Filter by creator's user ID |
| `pinned` | boolean \| null | Optional | Filter by pinned status |
| `mentions_user_id` | string | Optional | Filter notes that @mention this user ID |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Notes retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## POST /v1/accounts/{account_id}/notes

**Create Note**

Creates a new admin/team note attached to a resource.

Notes can be attached to:
- **user** - A user identity (requires issuer_id)
- **org** - An organization (requires issuer_id)
- **issuer** - An issuer (account-scoped, no issuer_id needed)
- **client** - An OAuth client (account-scoped, no issuer_id needed)

**Content Format:**
Notes support Markdown with special syntax for mentions and references:

- **@mentions**: `@[Display Name](user_id)` - Tags a team member
- **[[references]]**: `[[type:id]]` or `[[type:id|Display Text]]` - Links to another resource

Mentions and references are automatically extracted and stored for efficient querying (e.g., "find notes that mention me" or "find notes that reference this organization").

**Example content:**
```
Hey @[John Doe](usr_abc123), please review [[org:org_xyz|Acme Corp]].
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |

### Request body

Content type: `application/json`

Schema: `CreateNoteInput`

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Note created successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## GET /v1/accounts/{account_id}/notes/count

**Count Notes**

Counts the number of notes attached to a specific resource.

Useful for displaying note counts in UI without fetching all notes.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subject_type` | object | Required | The type of resource (user, org, issuer, client) |
| `subject_id` | string | Required | The ID of the resource |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Note count retrieved successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## GET /v1/accounts/{account_id}/notes/backlinks

**Get Note Backlinks**

Finds notes that reference a specific resource using [[references]].

This enables "backlink" queries - for example, finding all notes that mention a particular organization or user.

**Reference types:**
- user, org, issuer, client, webhook, api_key

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ref_type` | object | Required | The type of referenced resource |
| `ref_id` | string | Required | The ID of the referenced resource |
| `limit` | integer | Optional | Maximum number of notes to return (1-50, default: 10) |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Backlinks retrieved successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## GET /v1/accounts/{account_id}/notes/{note_id}

**Get Note**

Retrieves a single note by its ID.

The response includes:
- Note content and metadata
- **mentions** - Array of @mentioned team members extracted from content
- **references** - Array of [[referenced]] resources extracted from content

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `note_id` | string | Required | The unique identifier of the note |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Note retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## PATCH /v1/accounts/{account_id}/notes/{note_id}

**Update Note**

Updates an existing note's content or pinned status.

When content is updated, @mentions and [[references]] are automatically re-parsed and the stored mentions/references are updated accordingly.

**Updatable fields:**
- **content** - The note's markdown content
- **pinned** - Whether the note should appear at the top of lists

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `note_id` | string | Required | The unique identifier of the note |

### Request body

Content type: `application/json`

Schema: `UpdateNoteInput`

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Note updated successfully | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## DELETE /v1/accounts/{account_id}/notes/{note_id}

**Delete Note**

Permanently deletes a note.

This also removes all associated @mentions and [[references]] from the database (cascading delete).

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `note_id` | string | Required | The unique identifier of the note |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |