Core API Reference

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 — see the Core API overview for authentication, pagination, and idempotency, or try these endpoints in the interactive 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`