> ## Documentation Index > Fetch the complete documentation index at: https://docs.getaptly.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a board > Creates a new board. Requires the key's dedicated "Create Boards" access toggle to be enabled, in addition to `insert` permission — unlike the API key's other access toggles, this one defaults off and must be explicitly turned on in Setup → Developer. A `stage` field is always added automatically (a board can't render a Kanban/pipeline view without one) — `ticket` boards default to To Do / In Progress / Done, `deal` boards to the standard Aptly deal pipeline. `stage`, along with a handful of other reserved keys (`name`, `dueAt`, `relatedContacts`, and every card-document system key such as `_id`, `companyId`, `archived`), can't be used as a custom field's `uuid`. Only a safe, self-contained subset of Aptly's field types may be used for custom fields — relational types that reference other boards (e.g. `relatedAptlets`, `mirror`) and system/computed types the backend manages itself (e.g. `stageselect`, `calculation`) are rejected, since a freshly created board has nothing valid for them to point at yet. ## OpenAPI ````yaml /openapi.yaml post /api/boards openapi: 3.0.3 info: title: Aptly API version: '1.1' description: | The Aptly API lets external systems work with boards, contacts, inboxes, tasks, files, and other Aptly resources. Most endpoints accept an API key in the `x-token` header. Some endpoints also accept a delegate token or partner bearer token, as shown in each operation's security requirements, and explicitly public endpoints require no credential. API keys are scoped to a company and may be restricted to specific boards and read, insert, or update permissions; requests outside those restrictions receive a 403 `FORBIDDEN` response. servers: - url: https://core-api.getaptly.com description: Production security: - ApiKeyHeader: [] paths: /api/boards: post: tags: - Boards summary: Create a board description: > Creates a new board. Requires the key's dedicated "Create Boards" access toggle to be enabled, in addition to `insert` permission — unlike the API key's other access toggles, this one defaults off and must be explicitly turned on in Setup → Developer. A `stage` field is always added automatically (a board can't render a Kanban/pipeline view without one) — `ticket` boards default to To Do / In Progress / Done, `deal` boards to the standard Aptly deal pipeline. `stage`, along with a handful of other reserved keys (`name`, `dueAt`, `relatedContacts`, and every card-document system key such as `_id`, `companyId`, `archived`), can't be used as a custom field's `uuid`. Only a safe, self-contained subset of Aptly's field types may be used for custom fields — relational types that reference other boards (e.g. `relatedAptlets`, `mirror`) and system/computed types the backend manages itself (e.g. `stageselect`, `calculation`) are rejected, since a freshly created board has nothing valid for them to point at yet. operationId: createBoard requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: Board display name. boardType: type: string enum: - ticket - deal default: ticket description: >- Determines the default `stage` pipeline. Defaults to `ticket`. fields: type: array description: >- Optional custom fields to add, beyond the automatic `stage` field. items: type: object required: - name - type properties: name: type: string description: Field display name. type: $ref: '#/components/schemas/NewBoardFieldType' uuid: type: string description: > Optional explicit field key, used later as the key for this field's value in card create/update calls. Must match `^[a-zA-Z][a-zA-Z0-9_]{0,63}$`. Auto-generated when omitted. optional: type: boolean default: true pinned: type: boolean default: false description: Pin this field to the card's Kanban view. defaultValue: type: string data: type: array description: > Required (non-empty) for `singleselect` and `multiselect` — the field's option list. Not used by the other types. items: type: object required: - label properties: label: type: string uuid: type: string description: Auto-generated when omitted. example: name: Maintenance Requests boardType: ticket fields: - name: Priority type: singleselect data: - label: Low - label: Medium - label: High responses: '201': description: Board created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Board' '400': description: > `VALIDATION_ERROR` - missing/invalid `name`, `boardType`, or a `fields` entry (per-field `meta.issues`, e.g. `fields.0.type`), or a reserved/duplicate field `uuid`. content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: > This API key does not have insert permission, or does not have the dedicated "Create Boards" access enabled for this key. content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyHeader: [] - DelegateToken: [] components: schemas: NewBoardFieldType: type: string description: > The field types that can be created through the API (`POST /api/boards` and `POST /api/board/{boardId}/configuration/fields`). The value column is what a card stores and what the card API (`POST /api/board/{boardId}`) accepts under the field's `uuid`. | `type` | Label | Card value | |---|---|---| | `string` | Short Text | string | | `text` | Long Text | string | | `rich-text` | Rich Text | string (HTML) | | `number` | Number | number | | `money` | Currency | decimal number in requests (`1500.5`); returned as `{ amount, currency }` | | `percent` | Percent | number | | `multiplier` | Multiplier | number | | `boolean` | Checkbox | boolean | | `date` | Date | date | | `datetime-local` | Date and Time | date | | `email` | Email | string | | `emails` | Multiple Emails | string[] | | `tel` | Phone Number | string | | `phones` | Multiple Phone Numbers | array of phone objects | | `url` | URL | string | | `address` | Address | address object | | `person` | Link to a Single Contact | `{ _id }` (or `null` to clear); the contact must exist | | `persons` | Link to Multiple Contacts | array of `{ _id }` | | `user` | Team Member | user id | | `file` | Single Attachment | file id | | `files` | Multiple Attachments | file ids | | `heroImage` | Cover Photo | file id (the card's Kanban thumbnail) | | `embedVideo` | Embed Video | video URL string | | `stringList` | Text List | string[] | | `tags` | Tags | string[] | | `singleselect` | Dropdown | the chosen option's label - **requires `data`** | | `multiselect` | Multiple Select | array of option labels - **requires `data`** | | `checkboxlist` | Task List | array of `{ _id, checked, title }` (no `data`) | Relational and system types (`relatedAptlets`, `mirror`, `location`, `unit`, `stageselect`, `calculation`, and similar) can't be created through the API; boards built in the Aptly app can still contain them and they appear when reading fields. enum: - string - text - rich-text - number - money - percent - multiplier - boolean - date - datetime-local - email - emails - tel - phones - url - address - person - persons - user - file - files - heroImage - embedVideo - stringList - tags - singleselect - multiselect - checkboxlist Board: type: object properties: uuid: type: string description: Board UUID — use this as `boardId` in board/card endpoints. name: type: string description: Display name of the board. endpoints: type: array description: Pre-built endpoint URLs for this board. items: type: object properties: method: type: string description: HTTP method. url: type: string description: Full endpoint URL. description: type: string description: What the endpoint does. ValidationError: type: object description: > Returned with HTTP 400 when the request body fails shape validation (wrong type, missing required field, malformed email/phone number, value out of bounds). `meta.issues` lists every offending field. properties: error: type: object properties: code: type: string enum: - VALIDATION_ERROR message: type: string example: One or more fields are invalid meta: type: object properties: issues: type: array items: type: object properties: field: type: string description: >- Dotted path to the offending property (for example `to.0.value`); empty for a problem with the body as a whole. example: to.0.value code: type: string description: >- Machine-readable issue code (for example `invalid_type`, `invalid_format`, `too_small`). example: invalid_format message: type: string example: must be a valid email address requestId: type: string Error: type: object properties: error: type: string message: type: string securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-token DelegateToken: type: apiKey in: header name: Authorization description: 'Delegate token issued by the platform. Format: `DelegateToken `' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.