> ## Documentation Index > Fetch the complete documentation index at: https://developer.folk.app/llms.txt > Use this file to discover all available pages before exploring further. # Create a note > Create a new note in the workspace. Create a note linked to a person, company or deal. ### Visibility The visibility of the note can be set to `public` or `private`. * `public`: The note is visible to all users in the workspace. * `private`: The note is visible only to the current user. ### Content The content of the note can be in plain text or in markdown format. We support the full CommonMark [basic syntax](https://www.markdownguide.org/basic-syntax/), including: * Headings * Bold * Italic * Lists * Links * Images * Blockquotes * Horizontal rules * Code #### Mentions We also support mentioning workspace members using a simple markdown link to the [GET /v1/users/\{userId} endpoint](/api-reference/users/get-a-user). ```markdown theme={null} [](https://api.folk.app/v1/users/) ``` For example, to mention user `John Doe` with ID `usr_6526333c-1502-46e3-aa01-8f6130f69814`: ```markdown theme={null} This is a note mentioning [John Doe](https://api.folk.app/v1/users/usr_6526333c-1502-46e3-aa01-8f6130f69814) ``` To retrieve the user ID, you can use the [GET /v1/users endpoint](/api-reference/users/list-users). You can use any value as the user name. Our system will always replace it with the real user name of the workspace member mentioned. Providing an invalid link, a wrong user id, or a user id that does not exist will not trigger any error. Always respect the syntax and use ids retrieved from the API to make sure the mention is valid and the workspace member is notified. #### Attachments We currently do not support direct attachment upload. However, you can use any bucket storage service to upload files and reference them in the note content using a link, as long as the file is publicly accessible. Example: ```markdown theme={null} [PDF link](https://my-bucket.s3.eu-west-1.amazonaws.com/my-file.pdf) ``` ## OpenAPI ````yaml post /v1/notes openapi: 3.1.0 info: title: Folk External API description: >- Folk's public REST API lets you manage workspaces, groups, contacts, and real-time triggers. version: '2025-06-09' contact: name: folk email: tech@folk.app url: https://folk.app servers: - url: https://api.folk.app description: Folk's public API production base URL. x-internal: false security: [] tags: - name: Companies description: Operations related to companies. - name: Deals description: Operations related to deals. - name: Groups description: Operations related to groups. - name: Interactions description: Operations related to interactions. - name: Notes description: Operations related to notes. - name: People description: Operations related to people. - name: Reminders description: Operations related to reminders. - name: Tasks description: Operations related to tasks. - name: Users description: Operations related to users. - name: Webhooks description: Operations related to webhooks. paths: /v1/notes: post: tags: - Notes summary: Create a note description: Create a new note in the workspace. operationId: createNote requestBody: required: true content: application/json: schema: type: object properties: entity: type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id additionalProperties: false description: >- The entity connected to the note. You can link people, companies and deals. example: id: per_55175e81-9a52-4ac3-930e-82792c23499b visibility: type: string enum: - public - private description: >- The visibility of the note. - `public`: The note is visible to all users in the workspace. - `private`: The note is visible only to the current user. content: type: string minLength: 1 maxLength: 100000 description: >- The content of the note. Can be in plain text or in markdown format. example: This is a note about **John Doe** parentNote: type: object properties: id: type: string minLength: 40 maxLength: 40 required: - id additionalProperties: false description: The parent note, if this note is a reply to another note. example: id: nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c required: - entity - visibility - content additionalProperties: false responses: '200': description: The note created in the workspace. links: updateNote: operationId: updateNote parameters: noteId: $response.body#/data/id description: >- The id returned by the `POST /v1/notes` operation can be used as an input to the `PATCH /v1/notes/:noteId` operation to update the note. getNote: operationId: getNote parameters: companyId: $response.body#/data/id description: >- The id returned by the `POST /v1/notes` operation can be used as an input to the `GET /v1/notes/:noteId` operation to retrieve the note. deleteNote: operationId: deleteNote parameters: noteId: $response.body#/data/id description: >- The id returned by the `POST /v1/notes` operation can be used as an input to the `DELETE /v1/notes/:noteId` operation to delete the note. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Note' deprecations: type: array items: type: string example: - This field is deprecated required: - data example: data: id: nte_91118b73-5a75-480b-b8e3-a33671c35cdc entity: id: per_55175e81-9a52-4ac3-930e-82792c23499b entityType: person fullName: John Doe visibility: public content: This is a note about John Doe author: type: user id: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c fullName: John Doe email: john.doe@example.com deleted: false createdAt: '2021-01-01T00:00:00.000Z' parentNote: id: nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c entity: id: per_55175e81-9a52-4ac3-930e-82792c23499b entityType: person fullName: John Doe content: This is a parent note about John Doe visibility: public author: type: user id: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c fullName: John Doe email: john.doe@example.com deleted: false createdAt: '2021-01-01T00:00:00.000Z' deleted: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - bearerApiKeyAuth: [] components: headers: X-RateLimit-Limit: schema: type: integer example: 1000 description: >- The maximum number of requests that you can make in the current rate limit window. X-RateLimit-Remaining: schema: type: integer example: 998 description: The number of requests remaining in the current rate limit window. X-RateLimit-Reset: schema: type: integer example: 1747322958 description: >- The time at which the current rate limit window resets, in UTC epoch seconds. Retry-After: schema: type: integer example: 60 description: >- The number of seconds to wait before making a new request after hitting the rate limit. schemas: Note: type: object properties: id: type: string entity: type: object properties: id: type: string minLength: 40 maxLength: 40 description: The ID of the entity connected to the note. example: per_55175e81-9a52-4ac3-930e-82792c23499b entityType: type: string enum: - person - company - object description: >- The type of the entity connected to the note. Can be `person`, `company` or `object`. example: person fullName: type: string maxLength: 1000 description: The full name of the entity connected to the note. example: John Doe required: - id - entityType - fullName content: type: string minLength: 1 maxLength: 100000 description: The content of the note. Can be in plain text or in markdown format. example: This is a note about **John Doe** visibility: type: string enum: - public - private description: |- The visibility of the note. - `public`: The note is visible to all users in the workspace. - `private`: The note is visible only to the current user. author: anyOf: - type: object properties: type: type: string enum: - user description: >- The type of the author of the note, it can be a user or a folk assistant. example: user id: type: string description: The ID of the author of the note. example: usr_55175e81-9a52-4ac3-930e-82792c23499b fullName: type: string maxLength: 1000 description: The full name of the author of the note. example: John Doe email: type: string maxLength: 254 format: email description: The email of the author of the note. example: john.doe@example.com deleted: type: boolean enum: - false description: >- Whether the author has been deleted and does not exist anymore. example: false required: - type - id - fullName - email - deleted - type: object properties: type: type: string enum: - assistant description: >- The type of the author of the note, it can be a user or a folk assistant. example: assistant fullName: type: string maxLength: 1000 description: The name of the folk assistant that created the note. example: Research assistant required: - type - fullName - type: object properties: type: type: string enum: - user description: >- The type of the author of the note, it can be a user or a folk assistant. example: user id: type: string deleted: type: boolean enum: - true description: >- Whether the author has been deleted and does not exist anymore. example: true required: - type - id - deleted createdAt: type: - string - 'null' minLength: 20 maxLength: 40 description: The date and time the note was created, in ISO format. example: '2021-01-01T00:00:00.000Z' parentNote: oneOf: - type: object properties: id: type: string deleted: type: boolean enum: - true description: >- Whether the parent note has been deleted and does not exist anymore. example: true required: - id - deleted - type: object properties: id: type: string entity: type: object properties: id: type: string minLength: 40 maxLength: 40 description: The ID of the entity connected to the note. example: per_55175e81-9a52-4ac3-930e-82792c23499b entityType: type: string enum: - person - company - object description: >- The type of the entity connected to the note. Can be `person`, `company` or `object`. example: person fullName: type: string maxLength: 1000 description: The full name of the entity connected to the note. example: John Doe required: - id - entityType - fullName content: type: - string - 'null' minLength: 1 maxLength: 100000 description: >- The content of the parent note. If the parent note is not visible to the current user, this field will be null. example: This is a parent note about John Doe visibility: type: string enum: - public - private description: >- The visibility of the note. - `public`: The note is visible to all users in the workspace. - `private`: The note is visible only to the current user. author: anyOf: - type: object properties: type: type: string enum: - user description: >- The type of the author of the note, it can be a user or a folk assistant. example: user id: type: string description: The ID of the author of the note. example: usr_55175e81-9a52-4ac3-930e-82792c23499b fullName: type: string maxLength: 1000 description: The full name of the author of the note. example: John Doe email: type: string maxLength: 254 format: email description: The email of the author of the note. example: john.doe@example.com deleted: type: boolean enum: - false description: >- Whether the author has been deleted and does not exist anymore. example: false required: - type - id - fullName - email - deleted - type: object properties: type: type: string enum: - assistant description: >- The type of the author of the note, it can be a user or a folk assistant. example: assistant fullName: type: string maxLength: 1000 description: >- The name of the folk assistant that created the note. example: Research assistant required: - type - fullName - type: object properties: type: type: string enum: - user description: >- The type of the author of the note, it can be a user or a folk assistant. example: user id: type: string deleted: type: boolean enum: - true description: >- Whether the author has been deleted and does not exist anymore. example: true required: - type - id - deleted createdAt: type: - string - 'null' minLength: 20 maxLength: 40 description: >- The date and time the parent note was created, in ISO format. example: '2021-01-01T00:00:00.000Z' deleted: type: boolean enum: - false description: >- Whether the parent note has been deleted and does not exist anymore. example: false required: - id - entity - content - visibility - author - createdAt - deleted - type: 'null' description: The parent note, if this note is a reply to another note. example: id: nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c entity: id: per_55175e81-9a52-4ac3-930e-82792c23499b entityType: person fullName: John Doe content: This is a parent note about John Doe visibility: public author: type: user id: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c fullName: John Doe email: john.doe@example.com deleted: false createdAt: '2021-01-01T00:00:00.000Z' deleted: false required: - id - entity - content - visibility - author - createdAt - parentNote description: A note linked to an entity. example: id: nte_91118b73-5a75-480b-b8e3-a33671c35cdc entity: id: per_55175e81-9a52-4ac3-930e-82792c23499b entityType: person fullName: John Doe visibility: public content: This is a note about John Doe author: type: user id: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c fullName: John Doe email: john.doe@example.com deleted: false createdAt: '2021-01-01T00:00:00.000Z' parentNote: id: nte_14c18444-a0c7-459a-86b0-ccd70ebcd65c entity: id: per_55175e81-9a52-4ac3-930e-82792c23499b entityType: person fullName: John Doe content: This is a parent note about John Doe visibility: public author: type: user id: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c fullName: John Doe email: john.doe@example.com deleted: false createdAt: '2021-01-01T00:00:00.000Z' deleted: false Error: type: object properties: error: type: object properties: code: type: string example: RATE_LIMIT_EXCEEDED message: type: string example: You have exceeded your rate limit. documentationUrl: type: string format: uri example: https://developer.folk.app/api-reference/errors#rate-limiting requestId: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 timestamp: type: string format: date-time example: '2025-10-01T12:00:00Z' details: type: object additionalProperties: true example: limit: 1000 remaining: 0 retryAfter: '2025-10-01T12:00:00Z' required: - code - message - documentationUrl - requestId - timestamp required: - error description: Error response containing error details. responses: BadRequest: description: The request was unacceptable, often due to missing an invalid parameter. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_REQUEST message: The request was invalid. documentationUrl: https://developer.folk.app/api-reference/errors#bad-request requestId: 123e4567-e89b-12d3-a456-426614174000 timestamp: '2025-10-01T12:00:00Z' Unauthorized: description: No valid API key provided. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: No valid API key provided. documentationUrl: https://developer.folk.app/api-reference/errors#unauthorized requestId: 123e4567-e89b-12d3-a456-426614174000 timestamp: '2025-10-01T12:00:00Z' Forbidden: description: The API key doesn’t have permissions to perform the request. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: FORBIDDEN message: The API key doesn’t have permissions to perform the request. documentationUrl: https://developer.folk.app/api-reference/errors#forbidden requestId: 123e4567-e89b-12d3-a456-426614174000 timestamp: '2025-10-01T12:00:00Z' NotFound: description: The requested resource doesn’t exist. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RESOURCE_NOT_FOUND message: The requested resource was not found. documentationUrl: https://developer.folk.app/api-reference/errors#not-found requestId: 123e4567-e89b-12d3-a456-426614174000 timestamp: '2025-10-01T12:00:00Z' UnprocessableEntity: description: >- The request was unacceptable, often due to missing or invalid parameters. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNPROCESSABLE_ENTITY message: Invalid query parameters documentationUrl: >- https://developer.folk.app/api-reference/errors#unprocessable-entity details: issues: - code: too_small minimum: 1 type: number inclusive: true exact: false message: Number must be greater than or equal to 1 path: - limit requestId: 123e4567-e89b-12d3-a456-426614174000 timestamp: '2025-10-01T12:00:00Z' TooManyRequests: description: >- Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMIT_EXCEEDED message: The rate limit has been exceeded. documentationUrl: https://developer.folk.app/api-reference/errors#rate-limiting requestId: 123e4567-e89b-12d3-a456-426614174000 timestamp: '2025-10-01T12:00:00Z' details: limit: 1000 remaining: 0 retryAfter: '2025-10-01T12:00:00Z' InternalServerError: description: Something went wrong on our end. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_SERVER_ERROR message: An internal server error occurred. documentationUrl: >- https://developer.folk.app/api-reference/errors#internal-server-error requestId: 123e4567-e89b-12d3-a456-426614174000 timestamp: '2025-10-01T12:00:00Z' ServiceUnavailable: description: The server is overloaded or down for maintenance. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: SERVICE_UNAVAILABLE message: The service is currently unavailable. documentationUrl: >- https://developer.folk.app/api-reference/errors#service-unavailable requestId: 123e4567-e89b-12d3-a456-426614174000 timestamp: '2025-10-01T12:00:00Z' securitySchemes: bearerApiKeyAuth: type: http scheme: bearer description: API key for authentication ````