---
updatedAt: 2026-09-11T07:28:51.000Z
agentTools:
  projectIndex: https://docs.padlet.dev/llms.txt
---

# Create a post

Create a post in a board

Creates a new post on a board. Returns a [post object](https://docs.padlet.dev/reference/post-object).

> 📘 API key
>
> You will need to include your API key found <a href="https://padlet.com/dashboard/settings/developers" target="_blank">here</a>.
>
> Please include the key in your header. `{"X-API-KEY": <api_key>}`

<Callout icon="🔒" theme="default">
  ### Authorization required

  This endpoint requires admin access to the board. You must be an admin or owner of the board to access its data.
</Callout>

An example of a basic request body is displayed below. It follows the <a href="https://jsonapi.org/format/" target="_blank">JSON:API specification</a>.

```json Example request body
{
  "data": {
    "type": "post",
    "attributes": {
      "content": {
        "subject": "Test post",
        "body": "Created using the API!",
        "attachment": {
          "url": "http://example.com",
          "caption": "Example website"
        }
      },
      "color": "red",
      "customFields": {
        "field_abc123": "High Priority",
        "field_def456": "Project Alpha"
      }
    },
    "relationships": {
      "section": {
        "data": {
          "id": "abcd1234efgh5678"
        }
      }
    }
  }
}
```

### Body parameters

`*` required

`**`affects posts in certain formats

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Properties
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `type**`
      </td>

      <td>
        `string`
      </td>

      <td>
        Type should be set to `post`.
      </td>
    </tr>

    <tr>
      <td>
        `attributes.content*`
      </td>

      <td>
        `object`
      </td>

      <td>
        Content object holding subject, body and attachment information. 

        `content.subject` denotes the subject of the post. 

        `content.body` denotes the body of the post. 

        `content.attachment` is the attachment object of the post. Currently only supports url links and poll attachments. 

        One of subject, body or attachment is required to make a successful post request.
      </td>
    </tr>

    <tr>
      <td>
        `attributes.color`
      </td>

      <td>
        `string`
      </td>

      <td>
        Color of the post. 

        Allowed values are `red`,`orange`,`green`,`blue`,`purple`.
      </td>
    </tr>

    <tr>
      <td>
        `attributes.manualSortPosition`
      </td>

      <td>
        `object` 

        `previousPostId`:`string`
      </td>

      <td>
        Sets the position of the post relative to the post that comes before it. 

        `previousPostId` denotes the post that is on top or to the left of the post you are creating.
      </td>
    </tr>

    <tr>
      <td>
        `attributes.mapProps**`
      </td>

      <td>
        `object` 

        `latitude`:`float`\
        `longitude`:`float`\
        `locationName`:`string`
      </td>

      <td>
        Map properties of a post. Only affects posts in boards of map format. 

        `mapProps.latitude` denotes the latitude of the post in Padlet map format. 

        `mapProps.longitude` denotes the longitude of the post in Padlet map format. 

        `mapProps.locationName` denotes the custom location name. 

        Both latitude and longitude must be present to use `mapProps`.
      </td>
    </tr>

    <tr>
      <td>
        `attributes.canvasProps**`
      </td>

      <td>
        `object` 

        `left`:`int`\
        `right`:`int`\
        `width`:`int`
      </td>

      <td>
        Canvas property of a post. Only affects posts in boards of canvas format. 

        `canvasProps.left` denotes the left position of the post in Padlet canvas format. 

        `canvasProps.top` denotes the top position of the post in Padlet canvas format. 

        `canvasProps.width` denotes the width of the post. 

        All 3 are needed to use `canvasProps`
      </td>
    </tr>

    <tr>
      <td>
        `attributes.customFields`
      </td>

      <td>
        `object`
      </td>

      <td>
        Custom field values for this post. Keys should be the custom field IDs configured for the board, and values should be the field values. 

        Custom field IDs can be obtained from the board's `customFields` attribute.
      </td>
    </tr>

    <tr>
      <td>
        `relationships.section`
      </td>

      <td>
        `string`
      </td>

      <td>
        The section which the post belongs to. 

        `section.data.id` must belong to the wall. You can get this information via our [get board by id](https://docs.padlet.dev/reference/get-board-by-id) call with `include=sections` query params.
      </td>
    </tr>
  </tbody>
</Table>

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Endpoints",
    "version": "1.0",
    "description": "Read and create posts.",
    "contact": {
      "name": "Padlet Engineer",
      "email": "engine@wallwisher.com",
      "url": "https://legal.padlet.com"
    },
    "license": {
      "url": "https://legal.padlet.com",
      "name": "CPadlet"
    },
    "termsOfService": "https://legal.padlet.com"
  },
  "servers": [
    {
      "url": "https://api.padlet.dev/v1",
      "description": "V1."
    }
  ],
  "paths": {
    "/boards/{board_id}/posts": {
      "parameters": [
        {
          "$ref": "#/components/parameters/board_id"
        }
      ],
      "post": {
        "summary": "Create a post",
        "operationId": "add-post",
        "responses": {
          "201": {
            "$ref": "#/components/responses/newPost"
          },
          "400": {
            "$ref": "#/components/responses/400-bad-request"
          },
          "404": {
            "$ref": "#/components/responses/404-not-found"
          }
        },
        "requestBody": {
          "$ref": "#/components/requestBodies/addPost"
        },
        "description": "Create a post in a board",
        "tags": [
          "Post"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "x-internal": false
      }
    }
  },
  "components": {
    "schemas": {
      "id": {
        "title": "Id",
        "type": "string",
        "minLength": 16,
        "x-internal": false,
        "example": "abcd1234efgh5678x",
        "description": "ID of the object",
        "maxLength": 22
      },
      "base_attributes_read": {
        "title": "Base Attributes",
        "type": "object",
        "properties": {
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "x-internal": false
      },
      "user_attributes": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          },
          "shortName": {
            "type": "string"
          },
          "fullName": {
            "type": "string"
          },
          "avatarUrl": {
            "type": "string"
          }
        },
        "x-internal": false,
        "example": {
          "username": "j",
          "shortName": "Jerry",
          "fullName": "Jerry Seinfeld",
          "avatarUrl": "http://example.com"
        },
        "title": "User Attributes"
      },
      "post_read": {
        "type": "object",
        "x-examples": {
          "Hello": {
            "id": "hello1234world",
            "type": "post",
            "attributes": {
              "subject": "Hello World",
              "body": "Hello is a way of greeting"
            }
          }
        },
        "description": "The contents of a padlet are written in posts",
        "title": "Post",
        "x-internal": false,
        "properties": {
          "id": {
            "$ref": "#/components/schemas/id"
          },
          "type": {
            "type": "string",
            "enum": [
              "post"
            ]
          },
          "attributes": {
            "allOf": [
              {
                "$ref": "#/components/schemas/post_attributes_read"
              },
              {
                "$ref": "#/components/schemas/post_attributes_common"
              },
              {
                "$ref": "#/components/schemas/base_attributes_read"
              }
            ]
          },
          "relationships": {
            "allOf": [
              {
                "$ref": "#/components/schemas/belongs_to_board"
              },
              {
                "$ref": "#/components/schemas/belongs_to_section"
              }
            ]
          }
        }
      },
      "post_write": {
        "type": "object",
        "description": "The contents of a padlet are written in posts",
        "title": "Post",
        "x-internal": false,
        "required": [
          "type",
          "attributes"
        ],
        "properties": {
          "type": {
            "enum": [
              "post"
            ],
            "example": "post",
            "default": "post"
          },
          "attributes": {
            "allOf": [
              {
                "$ref": "#/components/schemas/post_attributes_write"
              },
              {
                "$ref": "#/components/schemas/post_attributes_common"
              }
            ]
          },
          "relationships": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/belongs_to_section"
              }
            ]
          }
        },
        "x-examples": {
          "Example 1": {
            "type": "post",
            "attributes": {
              "content": {
                "subject": "Hello",
                "body": "Hello is a way of greeting",
                "attachment": {
                  "url": "http://example.com",
                  "caption": "Example website",
                  "previewImageUrl": "http://example.com",
                  "embedCode": "<img src=\\\"http://example.com\\\" width=\\\"768\\\" height=\\\"561\\\" />",
                  "poll": null
                }
              },
              "manualSortPosition": {
                "previousPostId": "abcd1234efgh5678x"
              },
              "color": "red",
              "status": "approved",
              "canvasProps": {
                "left": 10,
                "top": 20,
                "width": 250
              },
              "mapProps": {
                "latitude": 0,
                "longitude": 0,
                "locationName": "string"
              },
              "customFields": {
                "field_abc123": "High Priority",
                "field_def456": "Project Alpha"
              }
            },
            "relationships": {
              "section": {
                "data": {
                  "id": "abcd1234efgh5678x",
                  "type": "section"
                }
              }
            }
          }
        }
      },
      "post_attributes_common": {
        "title": "Post Attributes",
        "type": "object",
        "x-internal": false,
        "properties": {
          "color": {
            "$ref": "#/components/schemas/post_color"
          },
          "status": {
            "$ref": "#/components/schemas/post_status"
          },
          "canvasProps": {
            "$ref": "#/components/schemas/post_canvas_props"
          },
          "mapProps": {
            "$ref": "#/components/schemas/post_map_props"
          }
        }
      },
      "post_attributes_read": {
        "title": "Post Attributes",
        "type": "object",
        "x-internal": false,
        "properties": {
          "author": {
            "$ref": "#/components/schemas/user_attributes"
          },
          "sortIndex": {
            "$ref": "#/components/schemas/sort_index"
          },
          "content": {
            "allOf": [
              {
                "$ref": "#/components/schemas/post_content_read"
              },
              {
                "$ref": "#/components/schemas/post_content_common"
              }
            ]
          },
          "webUrl": {
            "$ref": "#/components/schemas/post_weburl"
          },
          "customFields": {
            "type": "array",
            "description": "Array of custom field values for this post. Each object contains id (field ID, matching the keys of the board's customFields and, except for multi-select fields, the id of a definition in its customFieldDefinitions), key (field name) and value. Vote, rating and score fields have an object value with the response totals.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The custom field ID"
                },
                "key": {
                  "type": "string",
                  "description": "The custom field name"
                },
                "value": {
                  "oneOf": [
                    {
                      "type": "string",
                      "description": "The custom field value"
                    },
                    {
                      "type": "object",
                      "description": "Response totals for a vote, rating or score field",
                      "properties": {
                        "sum": {
                          "type": "integer",
                          "description": "Sum of all responses. For votes, upvotes count as 1 and downvotes as -1."
                        },
                        "count": {
                          "type": "integer",
                          "description": "Number of responses"
                        },
                        "userResponse": {
                          "type": "integer",
                          "description": "The requesting user's own response. Omitted when they have not responded."
                        }
                      }
                    }
                  ]
                }
              }
            },
            "example": [
              {
                "id": "Hg57JRb8",
                "key": "Priority",
                "value": "High"
              },
              {
                "id": "YLl9E2A8",
                "key": "Rating",
                "value": {
                  "sum": 9,
                  "count": 2,
                  "userResponse": 5
                }
              }
            ]
          }
        }
      },
      "post_attributes_write": {
        "title": "Post Attributes",
        "type": "object",
        "x-internal": false,
        "properties": {
          "content": {
            "$ref": "#/components/schemas/post_content_common"
          },
          "manualSortPosition": {
            "$ref": "#/components/schemas/manual_sort_position"
          },
          "customFields": {
            "type": "object",
            "description": "Custom field values for this post. Keys should be the custom field IDs configured for the board, and values should be the field values.",
            "example": {
              "field_abc123": "High Priority",
              "field_def456": "Project Alpha"
            }
          }
        },
        "required": [
          "content"
        ]
      },
      "post_content_common": {
        "type": "object",
        "example": {
          "subject": "Hello",
          "body": "Hello is a way of greeting",
          "attachment": {
            "url": "http://example.com",
            "caption": "Example website",
            "previewImageUrl": "http://example.com",
            "embedCode": "<img src=\\\"http://example.com\\\" width=\\\"768\\\" height=\\\"561\\\" />",
            "poll": null
          }
        },
        "x-internal": false,
        "title": "Post Content",
        "properties": {
          "subject": {
            "type": "string",
            "maxLength": 500
          },
          "body": {
            "type": "string",
            "maxLength": 10000
          },
          "attachment": {
            "$ref": "#/components/schemas/post_attachment"
          }
        }
      },
      "post_content_read": {
        "type": "object",
        "x-examples": {},
        "x-internal": false,
        "properties": {
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "title": "Post Content"
      },
      "post_canvas_props": {
        "type": "object",
        "example": {
          "left": 10,
          "top": 20,
          "width": 250
        },
        "title": "Post Properties In Canvas",
        "properties": {
          "left": {
            "type": "integer",
            "format": "int32"
          },
          "top": {
            "type": "integer",
            "format": "int32"
          },
          "width": {
            "type": "integer",
            "format": "int32"
          }
        }
      },
      "post_map_props": {
        "title": "Post Properties In Map",
        "type": "object",
        "properties": {
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "locationName": {
            "type": "string"
          }
        }
      },
      "post_color": {
        "title": "Post Color",
        "type": "string",
        "nullable": true,
        "enum": [
          "red",
          "orange",
          "green",
          "blue",
          "purple"
        ],
        "example": "red",
        "x-internal": false
      },
      "post_status": {
        "title": "Post Status",
        "type": "string",
        "enum": [
          "approved",
          "pending_moderation",
          "scheduled"
        ],
        "example": "approved",
        "x-internal": false,
        "nullable": true,
        "description": ""
      },
      "post_attachment": {
        "title": "Post Attachment",
        "type": "object",
        "x-internal": false,
        "nullable": true,
        "properties": {
          "caption": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "previewImageUrl": {
            "type": "string",
            "example": "http://example.com",
            "nullable": true
          },
          "embedCode": {
            "type": "string",
            "example": "<img src=\\\"http://example.com\\\" width=\\\"768\\\" height=\\\"561\\\" />",
            "nullable": true
          },
          "poll": {
            "type": "object",
            "nullable": true,
            "properties": {
              "question": {
                "type": "string",
                "nullable": true
              },
              "choices": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "manual_sort_position": {
        "type": "object",
        "x-examples": {},
        "x-internal": false,
        "title": "Manual Sort Position",
        "properties": {
          "previousPostId": {
            "$ref": "#/components/schemas/id"
          }
        }
      },
      "sort_index": {
        "title": "Sort Index",
        "type": "number",
        "example": 113664000,
        "x-internal": false,
        "description": ""
      },
      "belongs_to_board": {
        "title": "belongs to Board",
        "type": "object",
        "properties": {
          "board": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "$ref": "#/components/schemas/id"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "board"
                    ]
                  }
                },
                "required": [
                  "id",
                  "type"
                ]
              }
            }
          }
        }
      },
      "belongs_to_section": {
        "title": "belongs to Section",
        "type": "object",
        "properties": {
          "section": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "$ref": "#/components/schemas/id"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "section"
                    ],
                    "readOnly": true
                  }
                },
                "required": [
                  "id",
                  "type"
                ]
              }
            }
          }
        }
      },
      "post_weburl": {
        "title": "post_weburl",
        "type": "object",
        "properties": {
          "live": {
            "type": "string",
            "example": "https://padlet.dev/api1/my-shiny-padlet-abcd1234v9qj5snz/wish/1234"
          }
        }
      }
    },
    "parameters": {
      "board_id": {
        "name": "board_id",
        "in": "path",
        "schema": {
          "$ref": "#/components/schemas/id"
        },
        "description": "ID of the board where you are admin. You can find how to get this on our Introduction page.",
        "required": true
      }
    },
    "responses": {
      "newPost": {
        "description": "Returns resource object for the post with assigned id, sort index, and populated author information",
        "content": {
          "application/vnd.api+json": {
            "schema": {
              "type": "object",
              "properties": {
                "data": {
                  "$ref": "#/components/schemas/post_read"
                }
              }
            },
            "examples": {
              "Example 1": {
                "value": {
                  "data": {
                    "id": "abcd1234efgh5678x",
                    "type": "post",
                    "attributes": {
                      "author": {
                        "username": "j",
                        "shortName": "Jerry",
                        "fullName": "Jerry Seinfeld",
                        "avatarUrl": "http://example.com"
                      },
                      "sortIndex": 113664000,
                      "content": {
                        "updatedAt": "2019-08-24T14:15:22Z",
                        "subject": "Hello",
                        "body": "Hello is a way of greeting",
                        "attachment": {
                          "url": "http://example.com",
                          "caption": "Example website",
                          "previewImageUrl": "http://example.com",
                          "embedCode": "<img src=\\\"http://example.com\\\" width=\\\"768\\\" height=\\\"561\\\" />",
                          "poll": null
                        }
                      },
                      "webUrl": {
                        "live": "https://padlet.dev/api1/my-shiny-padlet-abcd1234v9qj5snz/wish/1234"
                      },
                      "color": "red",
                      "status": "approved",
                      "canvasProps": {
                        "left": 10,
                        "top": 20,
                        "width": 250
                      },
                      "mapProps": {
                        "latitude": 0,
                        "longitude": 0,
                        "locationName": "string"
                      },
                      "customFields": [
                        {
                          "key": "Priority",
                          "value": "High"
                        },
                        {
                          "key": "Category",
                          "value": "Project Alpha"
                        }
                      ],
                      "createdAt": "2019-08-24T14:15:22Z",
                      "updatedAt": "2019-08-24T14:15:22Z"
                    },
                    "relationships": {
                      "board": {
                        "data": {
                          "id": "abcd1234efgh5678x",
                          "type": "board"
                        }
                      },
                      "section": {
                        "data": {
                          "id": "abcd1234efgh5678x",
                          "type": "section"
                        }
                      }
                    }
                  }
                }
              },
              "Example 2": {
                "value": {
                  "data": {
                    "id": "abcd1234efgh5678x",
                    "type": "post",
                    "attributes": {
                      "author": {
                        "username": "j",
                        "shortName": "Jerry",
                        "fullName": "Jerry Seinfeld",
                        "avatarUrl": "http://example.com"
                      },
                      "sortIndex": 113664000,
                      "content": {
                        "updatedAt": "2019-08-24T14:15:22Z",
                        "subject": "Hello",
                        "body": "Hello is a way of greeting",
                        "attachment": {
                          "url": null,
                          "caption": "",
                          "poll": {
                            "question": "What's your favorite color?",
                            "choices": [
                              "Red",
                              "Blue",
                              "Green"
                            ]
                          }
                        }
                      },
                      "webUrl": {
                        "live": "https://padlet.dev/api1/my-shiny-padlet-abcd1234v9qj5snz/wish/1234"
                      },
                      "color": "red",
                      "status": "approved",
                      "canvasProps": {
                        "left": 10,
                        "top": 20,
                        "width": 250
                      },
                      "mapProps": {
                        "latitude": 0,
                        "longitude": 0,
                        "locationName": "string"
                      },
                      "customFields": [
                        {
                          "key": "Priority",
                          "value": "High"
                        },
                        {
                          "key": "Category",
                          "value": "Project Alpha"
                        }
                      ],
                      "createdAt": "2019-08-24T14:15:22Z",
                      "updatedAt": "2019-08-24T14:15:22Z"
                    },
                    "relationships": {
                      "board": {
                        "data": {
                          "id": "abcd1234efgh5678x",
                          "type": "board"
                        }
                      },
                      "section": {
                        "data": {
                          "id": "abcd1234efgh5678x",
                          "type": "section"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "404-not-found": {
        "description": "Object not found",
        "content": {
          "application/vnd.api+json": {
            "schema": {
              "type": "object",
              "properties": {
                "errors": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "status": {
                        "type": "string",
                        "example": "404"
                      },
                      "title": {
                        "type": "string",
                        "example": "Record not found"
                      },
                      "detail": {
                        "type": "string",
                        "example": "Record not found"
                      },
                      "code": {
                        "type": "string",
                        "example": "NOT_FOUND"
                      }
                    }
                  }
                }
              }
            },
            "example": {
              "errors": [
                {
                  "status": "404",
                  "title": "Record not found",
                  "detail": "Record not found",
                  "code": "NOT_FOUND"
                }
              ]
            }
          }
        }
      },
      "400-bad-request": {
        "description": "Bad Request",
        "content": {
          "application/vnd.api+json": {
            "schema": {
              "type": "object",
              "properties": {
                "errors": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "status": {
                        "type": "string",
                        "enum": [
                          "400"
                        ]
                      },
                      "code": {
                        "type": "string",
                        "description": "Machine-readable reason, e.g. BAD_REQUEST, PARAMETER_MISSING, BAD_JSON.",
                        "example": "BAD_REQUEST"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "requestBodies": {
      "addPost": {
        "content": {
          "application/vnd.api+json": {
            "schema": {
              "type": "object",
              "properties": {
                "data": {
                  "$ref": "#/components/schemas/post_write"
                }
              },
              "required": [
                "data"
              ]
            },
            "examples": {}
          }
        },
        "description": "Resource object for the post to be created"
      }
    },
    "securitySchemes": {
      "apiKey": {
        "name": "X-Api-Key",
        "type": "apiKey",
        "in": "header",
        "description": ""
      }
    }
  },
  "x-internal": false,
  "tags": [
    {
      "name": "Post",
      "description": "Operations related to posts inside a board."
    }
  ]
}
```