Notes — 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.
Base URL: https://api.authpi.com — explore every endpoint in the
interactive Core API reference.
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 |