--- updatedAt: 2026-04-14T15:25:24.000Z agentTools: projectIndex: https://developer.productboard.com/llms.txt --- # List notes Retrieves a list of notes from your workspace. > Without the `members:pii:read` scope, owner and creator email fields are returned as `[redacted]`. Filtering by `owner[email]` or `creator[email]` requires the `members:pii:read` scope. - Notes are sorted by creation date, newest first. - You can filter results using query parameters like `archived`, `processed`, `owner[email]`, `creator[email]`, `metadata[source][system]`, `metadata[source][recordId]`, or date/time ranges. - Use the `pageCursor` parameter to paginate through results. - Use the `fields` query parameter to optimize response size (default: all non-null fields, use `fields=all` to include null values, or `fields=name,tags` for specific fields). > To discover available fields use the [`/v2/notes/configurations`](#/paths/~1v2~1notes~1configurations/get) endpoint. ### Date/Time Filtering You can filter notes by creation or update timestamps using ISO-8601 date-time format: - Use `createdFrom` and `createdTo` to filter by creation date (inclusive bounds) - Use `updatedFrom` and `updatedTo` to filter by update date (inclusive bounds) - All date/time filters can be combined with each other and with other filters - Date ranges must be valid (From <= To) or a 400 error will be returned ### Filtering combinations Some combinations of the `archived` and `processed` flags result in empty or unexpected results. Use the following table to understand which notes are returned based on the filter values: | `archived` | `processed` | Result | |------------|-------------|---------------------------| | – | – | All notes | | `true` | `true` | None | | `true` | `false` | Archived | | `false` | `true` | Processed | | `false` | `false` | Unprocessed | | `true` | – | Archived | | `false` | – | Processed + unprocessed | | – | `true` | Processed | | – | `false` | Archived + unprocessed | > **Note**: Archived notes always return `processed: false` in the API response, regardless of their actual processing state. This is a known limitation of the system. # OpenAPI definition ```json { "openapi": "3.1.1", "info": { "title": "Notes", "description": "Productboard API v2 for managing notes and their relationships to other entities. Use these endpoints to create, list, update, and delete notes, and to link them to entities, companies, and other resources.", "version": "2.0.0", "contact": { "name": "Productboard Support", "url": "https://support.productboard.com", "email": "support@productboard.com" }, "license": { "name": "Productboard Proprietary", "url": "https://www.productboard.com/" } }, "servers": [ { "url": "https://api.productboard.com/v2", "description": "Production server" } ], "security": [ { "BearerAuth": [] }, { "OAuth2": [ "notes:read", "notes:write", "notes:delete" ] } ], "tags": [ { "name": "notes", "description": "Operations related to notes and their relationships." } ], "paths": { "/notes": { "get": { "tags": [ "notes" ], "summary": "List notes", "description": "Retrieves a list of notes from your workspace.\n\n> Without the `members:pii:read` scope, owner and creator email fields are returned as `[redacted]`. Filtering by `owner[email]` or `creator[email]` requires the `members:pii:read` scope.\n\n- Notes are sorted by creation date, newest first.\n- You can filter results using query parameters like `archived`, `processed`, `owner[email]`, `creator[email]`, `metadata[source][system]`, `metadata[source][recordId]`, or date/time ranges.\n- Use the `pageCursor` parameter to paginate through results.\n- Use the `fields` query parameter to optimize response size (default: all non-null fields, use `fields=all` to include null values, or `fields=name,tags` for specific fields).\n\n> To discover available fields\nuse the [`/v2/notes/configurations`](#/paths/~1v2~1notes~1configurations/get) endpoint.\n\n### Date/Time Filtering\n\nYou can filter notes by creation or update timestamps using ISO-8601 date-time format:\n- Use `createdFrom` and `createdTo` to filter by creation date (inclusive bounds)\n- Use `updatedFrom` and `updatedTo` to filter by update date (inclusive bounds)\n- All date/time filters can be combined with each other and with other filters\n- Date ranges must be valid (From <= To) or a 400 error will be returned\n\n### Filtering combinations\n\nSome combinations of the `archived` and `processed` flags result in empty or unexpected results.\nUse the following table to understand which notes are returned based on the filter values:\n\n| `archived` | `processed` | Result |\n|------------|-------------|---------------------------|\n| – | – | All notes |\n| `true` | `true` | None |\n| `true` | `false` | Archived |\n| `false` | `true` | Processed |\n| `false` | `false` | Unprocessed |\n| `true` | – | Archived |\n| `false` | – | Processed + unprocessed |\n| – | `true` | Processed |\n| – | `false` | Archived + unprocessed |\n\n> **Note**: Archived notes always return `processed: false` in the API response, regardless of their actual processing state. This is a known limitation of the system.\n", "operationId": "listNotes", "security": [ { "BearerAuth": [ "notes:read" ] } ], "parameters": [ { "name": "pageCursor", "in": "query", "description": "Cursor for pagination.", "required": false, "schema": { "type": "string" } }, { "name": "archived", "in": "query", "description": "Filter notes by archived status.", "required": false, "schema": { "type": "boolean", "example": true } }, { "name": "processed", "in": "query", "description": "Filter notes by processed status.", "required": false, "schema": { "type": "boolean", "example": true } }, { "name": "type[]", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NoteTypeInput" } }, "style": "form", "explode": true, "description": "Filter notes by one or more note types. Use array notation: `type[]=textNote&type[]=conversationNote`.\nCurrently supported note types:\n - textNote\n - conversationNote\n - opportunityNote\n\nLegacy aliases (simple, conversation, opportunity) are also accepted.\n" }, { "name": "owner[id]", "in": "query", "description": "Filter notes by owner UUID.", "required": false, "schema": { "type": "string", "format": "uuid" }, "example": "e9f642b4-f0f8-4acc-ba0c-acc76453f60e" }, { "name": "owner[email]", "in": "query", "description": "Filter notes by owner email.", "required": false, "schema": { "type": "string", "example": "jane.doe@example.com" } }, { "name": "creator[id]", "in": "query", "description": "Filter notes by creator UUID.", "required": false, "schema": { "type": "string", "format": "uuid" }, "example": "e9f642b4-f0f8-4acc-ba0c-acc76453f60e" }, { "name": "creator[email]", "in": "query", "description": "Filter notes by creator email.", "required": false, "schema": { "type": "string", "example": "john.doe@example.com" } }, { "name": "metadata[source][system]", "in": "query", "description": "Filter notes by the source system name from metadata.source.\nCan be combined with metadata[source][recordId] and other filters.\n", "required": false, "schema": { "type": "string", "example": "support" } }, { "name": "metadata[source][recordId]", "in": "query", "description": "Filter notes by the source record ID from metadata.source.\nCan be combined with metadata[source][system] and other filters.\n", "required": false, "schema": { "type": "string", "example": "ticket-12345" } }, { "name": "createdFrom", "in": "query", "description": "Filter notes created on or after this date/time (inclusive).\nMust be in ISO-8601 format (e.g., \"2023-10-01T12:00:00Z\").\nCan be combined with createdTo to define a range.\n", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2023-10-01T00:00:00Z" } }, { "name": "createdTo", "in": "query", "description": "Filter notes created on or before this date/time (inclusive).\nMust be in ISO-8601 format (e.g., \"2023-12-31T23:59:59Z\").\nCan be combined with createdFrom to define a range.\n", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2023-12-31T23:59:59Z" } }, { "name": "updatedFrom", "in": "query", "description": "Filter notes updated on or after this date/time (inclusive).\nMust be in ISO-8601 format (e.g., \"2023-10-01T12:00:00Z\").\nCan be combined with updatedTo to define a range.\n", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2023-10-01T00:00:00Z" } }, { "name": "updatedTo", "in": "query", "description": "Filter notes updated on or before this date/time (inclusive).\nMust be in ISO-8601 format (e.g., \"2023-12-31T23:59:59Z\").\nCan be combined with updatedFrom to define a range.\n", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2023-12-31T23:59:59Z" } }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "A paginated list of notes", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "links": { "$ref": "#/components/schemas/ListLinks" } } }, "examples": { "success": { "summary": "List of notes", "value": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "type": "textNote", "fields": { "name": "Customer feedback", "tags": [ { "name": "feedback" }, { "name": "q1" } ], "content": "Customer reported slow loading times on mobile app", "owner": { "id": "923e4567-e89b-12d3-a456-426614174008", "email": "john.doe@example.com" }, "creator": { "id": "e23e4567-e89b-12d3-a456-426614174013", "email": "creator@example.com" }, "processed": true, "archived": false, "createdAt": "2023-10-01T09:00:00Z", "updatedAt": "2023-10-02T14:00:00Z" }, "relationships": [ { "type": "customer", "target": { "id": "f23e4567-e89b-12d3-a456-426614174014", "type": "user", "links": { "self": "https://api.productboard.com/v2/users/f23e4567-e89b-12d3-a456-426614174014" } } }, { "type": "link", "target": { "id": "g23e4567-e89b-12d3-a456-426614174015", "type": "feature", "links": { "self": "https://api.productboard.com/v2/entities/g23e4567-e89b-12d3-a456-426614174015" } } } ], "links": { "self": "https://api.productboard.com/v2/notes/123e4567-e89b-12d3-a456-426614174000", "html": "https://example.productboard.com/all-notes/notes/42" } }, { "id": "223e4567-e89b-12d3-a456-426614174001", "type": "conversationNote", "fields": { "name": "Support conversation", "content": [ { "externalId": "b23e4567-e89b-12d3-a456-426614174010", "content": "Hello, I need help with the app", "authorName": "John Customer", "authorType": "customer", "timestamp": "2023-10-01T10:00:00Z" }, { "externalId": "c23e4567-e89b-12d3-a456-426614174011", "content": "Hi John, how can I help you today?", "authorName": "Support Agent", "authorType": "agent", "timestamp": "2023-10-01T10:05:00Z" } ], "tags": [ { "name": "support" } ], "owner": { "id": "d23e4567-e89b-12d3-a456-426614174012", "email": "support@example.com" }, "creator": { "id": "e23e4567-e89b-12d3-a456-426614174013", "email": "creator@example.com" }, "processed": true, "archived": false, "createdAt": "2023-10-01T10:00:00Z", "updatedAt": "2023-10-01T10:05:00Z" }, "relationships": [ { "type": "customer", "target": { "id": "h23e4567-e89b-12d3-a456-426614174016", "type": "company", "links": { "self": "https://api.productboard.com/v2/companies/h23e4567-e89b-12d3-a456-426614174016" } } } ], "links": { "self": "https://api.productboard.com/v2/notes/223e4567-e89b-12d3-a456-426614174001", "html": "https://example.productboard.com/all-notes/notes/43" } } ], "links": { "next": "https://api.productboard.com/v2/notes?pageCursor=next_cursor_value" } } }, "filterByOwnerEmail": { "summary": "List unarchived notes owned by a specific user (filter by owner email)", "description": "Example using query parameters: `?archived=false&owner[email]=john.doe@example.com`", "value": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "type": "textNote", "fields": { "name": "Customer feedback", "content": "Customer reported slow loading times on mobile app", "owner": { "id": "923e4567-e89b-12d3-a456-426614174008", "email": "john.doe@example.com" }, "creator": { "id": "e23e4567-e89b-12d3-a456-426614174013", "email": "creator@example.com" }, "processed": false, "archived": false }, "links": { "self": "https://api.productboard.com/v2/notes/123e4567-e89b-12d3-a456-426614174000", "html": "https://example.productboard.com/all-notes/notes/42" } } ], "links": { "next": null } } }, "filterByDateRange": { "summary": "List notes created within a specific date range", "description": "Example using query parameters: `?createdFrom=2023-10-01T00:00:00Z&createdTo=2023-12-31T23:59:59Z`", "value": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "type": "textNote", "fields": { "name": "Q4 feedback", "content": "Feedback collected during Q4", "processed": false, "archived": false }, "links": { "self": "https://api.productboard.com/v2/notes/123e4567-e89b-12d3-a456-426614174000", "html": "https://example.productboard.com/all-notes/notes/42" } }, { "id": "223e4567-e89b-12d3-a456-426614174001", "type": "textNote", "fields": { "name": "Another Q4 note", "content": "More Q4 feedback", "processed": true, "archived": false }, "links": { "self": "https://api.productboard.com/v2/notes/223e4567-e89b-12d3-a456-426614174001", "html": "https://example.productboard.com/all-notes/notes/43" } } ], "links": { "next": null } } }, "filterByUpdateTime": { "summary": "List notes updated after a specific time (for incremental sync)", "description": "Example using query parameter: `?updatedFrom=2024-01-01T00:00:00Z`", "value": { "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "type": "textNote", "fields": { "name": "Recently updated note", "content": "This note was recently modified", "processed": false, "archived": false }, "links": { "self": "https://api.productboard.com/v2/notes/123e4567-e89b-12d3-a456-426614174000", "html": "https://example.productboard.com/all-notes/notes/42" } } ], "links": { "next": null } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "408": { "$ref": "#/components/responses/RequestTimeoutResponse" }, "429": { "$ref": "#/components/responses/TooManyRequestsResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "API token authentication. Use your API token as the value of the Authorization header" }, "OAuth2": { "type": "oauth2", "description": "OAuth 2.0 authentication. Use this for user-authorized access to Productboard API.", "flows": { "authorizationCode": { "authorizationUrl": "https://app.productboard.com/oauth/authorize", "tokenUrl": "https://app.productboard.com/oauth/token", "scopes": { "notes:read": "Read access to notes", "notes:write": "Write access to create and modify notes", "notes:delete": "Delete notes" } } } } }, "schemas": { "NoteReference": { "type": "object", "description": "Minimal reference to a note resource containing only identifying information.\n", "required": [ "id", "type", "links" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/NoteType" }, "links": { "$ref": "#/components/schemas/NoteLinks" } } }, "NoteLinks": { "type": "object", "description": "Links for navigating note resources.", "required": [ "self", "html" ], "properties": { "self": { "type": "string", "format": "uri", "description": "URL of the note resource.", "example": "https://api.productboard.com/v2/notes/123e4567-e89b-12d3-a456-426614174000" }, "html": { "type": "string", "format": "uri", "description": "URL of the note in the Productboard UI.", "example": "https://example.productboard.com/all-notes/notes/42" } } }, "Note": { "description": "Full note resource with all fields and metadata.\n", "allOf": [ { "$ref": "#/components/schemas/NoteReference" }, { "type": "object", "required": [ "fields", "relationships", "createdAt", "updatedAt" ], "properties": { "fields": { "$ref": "#/components/schemas/NoteFields" }, "relationships": { "$ref": "#/components/schemas/NoteRelationships" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the note was created", "example": "2025-01-15T10:30:00Z" }, "metadata": { "$ref": "#/components/schemas/EntityMetadata" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the note was last updated", "example": "2025-01-15T14:45:00Z" } } } ] }, "EntityReferenceResponse": { "type": "object", "description": "Represents a reference to an entity in Productboard.\n", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/EntityType" }, "links": { "$ref": "#/components/schemas/ResourceLinks" } } }, "EntityType": { "type": "string", "description": "- Initially comes from PMM, where this value is called \"model\".\n- We are exposing it under more understandable \"type\".\n- Plural form is kept for consistency.\n", "example": "feature" }, "NoteType": { "type": "string", "enum": [ "textNote", "conversationNote", "opportunityNote" ], "example": "textNote" }, "NoteTypeInput": { "type": "string", "enum": [ "simple", "textNote", "conversation", "conversationNote", "opportunity", "opportunityNote" ], "example": "textNote" }, "NoteRelationship": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "customer", "link" ] }, "target": { "$ref": "#/components/schemas/EntityReferenceResponse" } } }, "NoteRelationships": { "type": "object", "description": "A collection of relationships connected to the note.\nThis includes:\n- Customer relationship (either a User or Company entity)\n- Product link relationships (e.g. linked features)\nThe list is paginated, to see the rest of the relationships follow the URL contained in the `links.next` attribute.\n", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NoteRelationship" } }, "links": { "$ref": "#/components/schemas/ListLinks" } } }, "NoteFields": { "type": "object", "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/NoteFieldValue" }, { "type": "null" } ] } }, "NoteFieldValue": { "description": "A list of possible value types of Note fields\n", "anyOf": [ { "$ref": "#/components/schemas/BooleanFieldValue" }, { "$ref": "#/components/schemas/ConversationNoteFieldValue" }, { "$ref": "#/components/schemas/DateFieldValue" }, { "$ref": "#/components/schemas/KeyValueFieldValue" }, { "$ref": "#/components/schemas/MemberFieldValue" }, { "$ref": "#/components/schemas/MultiSelectFieldValue" }, { "$ref": "#/components/schemas/NameFieldValue" }, { "$ref": "#/components/schemas/NumberFieldValue" }, { "$ref": "#/components/schemas/RichTextFieldValue" }, { "$ref": "#/components/schemas/SourceFieldValue" }, { "$ref": "#/components/schemas/TextFieldValue" }, { "$ref": "#/components/schemas/URLFieldValue" }, { "$ref": "#/components/schemas/UUIDFieldValue" } ] }, "ResourceLinks": { "type": "object", "required": [ "self" ], "properties": { "self": { "type": "string" } } }, "UUID": { "type": "string", "format": "uuid", "description": "A universally unique identifier (UUID).\n", "example": "123e4567-e89b-12d3-a456-426614174000" }, "ErrorSource": { "type": "object", "description": "An object containing references to the source of the error. It helps with location of the problematic field or parameter.\n", "properties": { "pointer": { "type": "string", "description": "JSON Pointer [RFC6901] to the associated entity in the request document.\n", "example": "/data/fields/status" }, "parameter": { "type": "string", "description": "Query parameter causing the error.\nUsed when the error is related to a query parameter rather than request body.\n", "example": "pageCursor" } } }, "Error": { "type": "object", "description": "Individual error object containing the details and context.\n", "required": [ "code", "title", "detail" ], "properties": { "code": { "type": "string", "description": "A unique, machine-readable and stable code that identifies this error.\nMust be consistent across all services and provide clear categorization.\nFormat: `category.subcategory.specificError`\n", "examples": [ "auth.accessDenied", "resource.notFound" ] }, "title": { "type": "string", "description": "A short, human-readable summary of the problem that doesn't change\nfrom occurrence to occurrence of the problem. Should provide immediate\nunderstanding of the error type.\n", "maxLength": 255, "example": "Missing required field" }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem.\nMay include suggestions for resolution but should not expose sensitive information.\n", "maxLength": 1000, "example": "Field 'status' is required." }, "source": { "$ref": "#/components/schemas/ErrorSource" } } }, "ErrorResponse": { "type": "object", "description": "Standard error response structure.\n", "required": [ "id", "errors" ], "properties": { "id": { "type": "string", "description": "A unique identifier for this specific occurrence of the problem.\nIt carries unique request/response ID which allows client\nand server to reference the exact instance of the error\nin logs or support communication.\n" }, "errors": { "type": "array", "description": "Array of error objects, multiple errors can be returned.", "items": { "$ref": "#/components/schemas/Error" }, "minItems": 1 } } }, "BooleanFieldValue": { "type": "boolean", "description": "Boolean value or flag. In the UI, it is usually represented as a single checkbox.\n# Validation\nValidate if value is `true` or `false`\n# Filtering\nWe support filtering by value\n", "example": true }, "ConversationNotePart": { "type": "object", "required": [ "externalId", "authorType", "content", "timestamp" ], "properties": { "externalId": { "type": "string", "description": "Unique reference of a part in the external system\n" }, "authorName": { "type": "string", "description": "Name of the author of the conversation part\n" }, "authorType": { "type": "string", "description": "Type of the author, either `customer` or `agent`\n", "enum": [ "customer", "agent" ] }, "content": { "type": "string", "description": "Content of the conversation part\n" }, "timestamp": { "type": "string", "description": "When the conversation part was created\n", "format": "date-time" } } }, "ConversationNoteFieldValue": { "description": "Conversation-style content with multiple parts representing a back-and-forth dialog.\n", "type": "array", "items": { "$ref": "#/components/schemas/ConversationNotePart" } }, "DateFieldValue": { "type": "string", "format": "date", "description": "Date and time in ISO 8601 format without time.\n\n# Validation\nValidate if provided value is a date string.\n\n# Filtering\nWe support only exact match.\n", "example": "2023-10-01" }, "KeyValueFieldValueItem": { "type": "object", "description": "Represents a field in key-value format.\n", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the field." }, "name": { "type": "string", "description": "Name of the field." }, "fieldType": { "type": "string", "description": "Type of the field.", "enum": [ "number", "string" ] }, "value": { "type": "string", "description": "Value of the field" } } }, "KeyValueFieldValue": { "type": "array", "description": "An array of key-value fields. Each field represents a specific piece of information.\n", "items": { "$ref": "#/components/schemas/KeyValueFieldValueItem" } }, "Email": { "type": "string", "maxLength": 256, "description": "The email of a Productboard user that has access to your workspace.", "example": "email@example.com" }, "ObfuscatedValue": { "type": "string", "enum": [ "[redacted]" ], "description": "The value `[redacted]`. Used to hide personally identifiable information in cases the request doesn't have the required `members:pii:read` OAuth2 scope.\n", "example": "[redacted]" }, "MemberFieldValue": { "type": "object", "description": "Member field value containing id and email.\n\nNote: When the `members:pii:read` scope is not present, the `email`\nfield will return `[redacted]` instead of actual value.\n", "required": [ "id", "email" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "email": { "anyOf": [ { "$ref": "#/components/schemas/Email" }, { "$ref": "#/components/schemas/ObfuscatedValue" } ] } } }, "SingleSelectFieldValue": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "example": { "id": "95db5914-36b0-45e9-8f6d-7f11a950ac1d", "name": "Example Option" } }, "MultiSelectFieldValue": { "type": "array", "items": { "$ref": "#/components/schemas/SingleSelectFieldValue" }, "example": [ { "id": "95db5914-36b0-45e9-8f6d-7f11a950ac1d", "name": "Example Option" } ] }, "NameFieldValue": { "type": "string", "minLength": 0, "maxLength": 255, "description": "A name field that can contain any text.\nThe exact format should be specified in the API documentation.\n\n# Validation\n\n# Filtering\nWe support only exact match.\n", "example": "Example Name" }, "NumberFieldValue": { "type": "number", "description": "A numeric field that can contain any number.\nThe exact format should be specified in the API documentation.\n\n# Validation\nValidate if provided value is a number.\nWe support integers or flows and negative numbers.\n\n# Filtering\nWe support only exact match.\n", "example": 123.45 }, "RichTextFieldValue": { "type": "string", "format": "html", "minLength": 0, "maxLength": 524288, "description": "Rich text content, which may include HTML or Markdown formatting.\nThe exact format should be specified in the API documentation.\n\n# Validation\n\n# Filtering\nNo filtering\n", "example": "

This is rich text.

" }, "SourceFieldValue": { "type": "object", "description": "Source information for the note content", "properties": { "id": { "type": [ "string", "null" ], "description": "Identifier of the source in an external system" }, "origin": { "type": [ "string", "null" ], "description": "Origin system name, e.g., crm, support, etc." }, "recordId": { "type": [ "string", "null" ], "description": "External source record ID for filtering and cross-referencing" }, "url": { "type": [ "string", "null" ], "description": "URL pointing to the source record" } } }, "TextFieldValue": { "type": "string", "minLength": 0, "maxLength": 255, "description": "A string field that can contain any text.\nThe exact format should be specified in the API documentation.\n\n# Validation\n\n# Filtering\nWe support only exact match. No wildcards or startWith/endWith.\n", "example": "Example String" }, "URLFieldValue": { "type": "string", "format": "uri", "description": "A URL field that can contain any valid URL.\nThe exact format should be specified in the API documentation.\n\n# Validation\nValidate if provided value is a URL.\n\n# Filtering\nWe support only exact match.\n", "example": "https://example.com" }, "UUIDFieldValue": { "type": "string", "format": "uuid", "description": "A universally unique identifier (UUID).\n\n# Validation\nValidate if provided value is an UUID.\n\n# Filtering\nN/A\n" }, "ListLinks": { "type": "object", "required": [ "next" ], "properties": { "next": { "type": [ "string", "null" ] } } }, "ApiSource": { "type": "object", "description": "Source metadata identifying the external system origin of a record.\n\n- `system`: Identifier for the external system (e.g., \"salesforce\", \"zendesk\"). Free-form string, no specific format enforced.\n- `recordId`: Identifier of the record in the external system (e.g., \"ticket-999\", \"acc-12345\"). Free-form string, no specific format enforced.\n- `url`: URL pointing to the source record in the external system\n", "properties": { "system": { "type": "string", "example": "zendesk" }, "recordId": { "type": "string", "example": "ticket-999" }, "url": { "type": "string", "format": "uri", "example": "https://example.zendesk.com/tickets/999" } } }, "EntityMetadata": { "type": "object", "description": "Metadata associated with a resource, including its external source.\n", "properties": { "source": { "$ref": "#/components/schemas/ApiSource" } } } }, "responses": { "BadRequestResponse": { "description": "Bad Request - Invalid input format or malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "schemaInvalid": { "summary": "Request does not satisfy schema", "value": { "id": "req-1234567890", "errors": [ { "code": "request.invalid", "title": "Request schema invalid", "detail": "The request does not satisfy the required schema. Field 'type' is required but was not provided.", "source": { "pointer": "/data/type" } } ] } }, "fieldInvalid": { "summary": "Invalid field value type", "value": { "id": "req-1234567891", "errors": [ { "code": "request.invalid", "title": "Request schema invalid", "detail": "Field 'fields/name' must be a string with maximum length of 255 characters, but received a number.", "source": { "pointer": "/data/fields/name" } } ] } }, "malformedJson": { "summary": "Malformed JSON syntax", "value": { "id": "req-1234567892", "errors": [ { "code": "request.malformed", "title": "Request malformed", "detail": "The request body contains invalid JSON syntax. Expected ',' or '}' at line 5, column 12." } ] } }, "invalidContentType": { "summary": "Invalid content type", "value": { "id": "req-1234567893", "errors": [ { "code": "request.malformed", "title": "Request malformed", "detail": "The Content-Type header must be 'application/json'. Received 'text/plain'." } ] } } } } } }, "UnauthorizedResponse": { "description": "Unauthorized - Missing or invalid authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingCredentials": { "summary": "Missing authentication credentials", "value": { "id": "req-2234567890", "errors": [ { "code": "auth.invalid", "title": "Invalid authentication", "detail": "Authentication credentials are missing." } ] } }, "invalidToken": { "summary": "Invalid or expired token", "value": { "id": "req-2234567891", "errors": [ { "code": "auth.invalid", "title": "Invalid authentication", "detail": "The provided authentication credentials are invalid or have expired. Please obtain new credentials and try again." } ] } }, "revokedCredentials": { "summary": "Revoked credentials", "value": { "id": "req-2234567892", "errors": [ { "code": "auth.invalid", "title": "Invalid authentication", "detail": "The authentication credentials have been revoked. Please contact your workspace administrator." } ] } } } } } }, "ForbiddenResponse": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "permissionDenied": { "summary": "Permission denied for resource", "value": { "id": "req-3234567890", "errors": [ { "code": "auth.accessDenied", "title": "Access denied", "detail": "You do not have permission to perform this operation on the specified resource. Contact your workspace administrator to request access." } ] } }, "insufficientScope": { "summary": "Insufficient OAuth scopes", "value": { "id": "req-3234567891", "errors": [ { "code": "auth.accessDenied", "title": "Access denied", "detail": "Your authentication token lacks the required OAuth scopes to perform this operation. Please re-authenticate with the necessary scopes." } ] } }, "readOnlyRole": { "summary": "Read-only role restriction", "value": { "id": "req-3234567892", "errors": [ { "code": "auth.accessDenied", "title": "Access denied", "detail": "Your user role does not permit this operation. Please contact your workspace administrator." } ] } } } } } }, "NotFoundResponse": { "description": "Not Found - The requested resource does not exist or is not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "resourceNotFoundById": { "summary": "Resource not found by ID", "value": { "id": "req-4234567890", "errors": [ { "code": "resource.notFound", "title": "Resource not found", "detail": "The requested resource could not be found or you do not have permission to access it." } ] } }, "routeNotFound": { "summary": "API route not found", "value": { "id": "req-4234567893", "errors": [ { "code": "route.notFound", "title": "Route not found", "detail": "The requested URL path does not match any defined API route. Please check the API documentation for valid endpoints." } ] } } } } } }, "RequestTimeoutResponse": { "description": "Request Timeout - The server did not receive a complete request within the allowed time", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "requestTimeout": { "summary": "Request timeout", "value": { "id": "req-5234567890", "errors": [ { "code": "request.timeout", "title": "Request timeout", "detail": "The request took too long to process and was terminated. Try simplifying your request or try again later." } ] } } } } } }, "TooManyRequestsResponse": { "description": "Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rateLimitExceeded": { "summary": "Rate limit exceeded", "value": { "id": "req-7234567890", "errors": [ { "code": "rate.limitExceeded", "title": "Rate limit exceeded", "detail": "You have exceeded the allowed number of API requests. Please wait before making additional requests." } ] } } } } } }, "InternalServerErrorResponse": { "description": "Internal Server Error - An unexpected error occurred on the server, please retry or contact support", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internalServerError": { "summary": "Unexpected server error", "value": { "id": "req-8234567890", "errors": [ { "code": "internal.serverError", "title": "Internal server error", "detail": "An unexpected error occurred while processing your request. Please try again later. If the problem persists, contact support with the correlation ID." } ] } } } } } } }, "parameters": { "fields": { "name": "fields", "in": "query", "description": "Controls which fields are returned in the response to optimize bandwidth and tailor data to your needs.\n\n**Options:**\n- Not specified: Returns only fields with non-empty values (default)\n- `fields[]=all`: Returns all fields, including those with `null` values\n- `fields[]=name&fields[]=tags`: Returns only the specified fields\n\n**Notes:**\n- When specific fields are requested, they are returned even if they have null/empty values\n- Unknown field IDs result in a 400 Bad Request error\n- Combining `all` with specific field IDs results in a 400 Bad Request error\n\nFor detailed usage, examples, and field discovery, see [Response Field Control](https://developer.productboard.com/v2.0.0/reference/response-field-control).\n", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "sparse": { "summary": "Retrieve only specific fields", "value": [ "name", "tags", "content" ] }, "all": { "summary": "Include all fields including null values", "value": [ "all" ] } } } } }, "x-readme": { "samples-languages": [ "shell", "javascript", "ruby" ] } } ```