# Create a new post

Creates a new post (feedback submission) in the specified board.

### Required Fields

- title - Post title (minimum 2 characters)
- boardId - Board ID to create the post in

### Optional Fields

- content - Post content in HTML format
- tags - Array of tag names to attach
- statusId - Status ID to set (defaults to board's default status)
- commentsEnabled - Whether comments are allowed (default: true)
- inReview - Whether post is pending moderation (default: false)
- customFields - Custom field values as key-value pairs
- eta - Estimated completion date (Unix timestamp or ISO date)
- assigneeId - Admin ID to assign this post to
- visibility - Post-level visibility restriction: 'public' (no additional restrictions), 'authorOnly' (only author and admins), or 'companyOnly' (only users in author's company). Note: even 'public' posts are still subject to board-level and organization-level access controls.

### Author Attribution

For posts created on behalf of users, use the author object:
- id - Featurebase user ID
- userId - External SSO user ID
- email - User's email address
- name - Display name
- profilePicture - Profile picture URL

Resolution priority: id > userId > email > authenticated user

### Backdating (Imports)

- createdAt - Override creation date for importing historical data

### Response

Returns the created post object with all fields populated.

Endpoint: POST /v2/posts
Version: 2026-01-01.nova
Security: bearerAuth

## Header parameters:

  - `Featurebase-Version` (string)
    API version for this request. Defaults to your organization's configured API version if not specified.
    Example: "2026-01-01.nova"

## Request fields (application/json):

  - `title` (string, required)
    Post title
    Example: "Add dark mode support"

  - `content` (string)
    Post content (HTML)
    Example: "<p>It would be great to have dark mode.</p>"

  - `boardId` (string, required)
    Board ID to create post in
    Example: "507f1f77bcf86cd799439011"

  - `tags` (any)
    Tag names to attach
    Example: ["feature","ui"]

  - `commentsEnabled` (boolean,null)
    Whether comments are enabled on this post
    Example: true

  - `statusId` (string)
    Status ID to set
    Example: "507f1f77bcf86cd799439012"

  - `author` (object)
    Author to attribute the post to. If not provided, uses the authenticated user. Supports multiple identification methods: id (Featurebase ID), userId (external SSO ID), or email.

  - `author.id` (string)
    Featurebase user ID to attribute content to
    Example: "507f1f77bcf86cd799439011"

  - `author.userId` (string)
    External user ID from your system (matched via SSO)
    Example: "usr_12345"

  - `author.email` (string)
    Author email (used to find or create user)
    Example: "john@example.com"

  - `author.name` (string)
    Author display name
    Example: "John Doe"

  - `author.profilePicture` (string)
    Author profile picture URL
    Example: "https://example.com/avatar.png"

  - `inReview` (boolean,null)
    Whether post is pending moderation

  - `customFields` (object)
    Custom field values. Keys must be valid ObjectIds. Values can be: string, boolean, number, ISO date string, array of strings, ObjectId string, or null.
    Example: {"507f1f77bcf86cd799439011":"high"}

  - `eta` (string,null)
    Estimated completion date
    Example: "2025-12-31T23:59:59.000Z"

  - `createdAt` (string,null)
    Creation date (for backdating imports)
    Example: "2025-01-15T10:30:00.000Z"

  - `assigneeId` (string)
    Admin ID to assign this post to
    Example: "507f1f77bcf86cd799439013"

  - `visibility` (string)
    Post visibility. 'public' = visible to all users, 'authorOnly' = only visible to the author and admins, 'companyOnly' = only visible to users in the same company as the author
    Enum: "public", "authorOnly", "companyOnly"

  - `upvotes` (integer,null)
    Initial upvotes count. Defaults to 1 (post author is automatically added as voter). Use 0 to create a post without any votes.
    Example: 5

## Response 201 fields (application/json):

  - `object` (string, required)
    Object type identifier
    Enum: "post"

  - `id` (string, required)
    Unique identifier
    Example: "507f1f77bcf86cd799439011"

  - `slug` (string, required)
    URL-friendly slug
    Example: "add-dark-mode-support"

  - `postUrl` (string, required)
    Full URL to view the post
    Example: "https://feedback.example.com/p/add-dark-mode-support"

  - `title` (string, required)
    Post title
    Example: "Add dark mode support"

  - `content` (string, required)
    Post content in HTML format
    Example: "<p>It would be great to have a dark mode option for the dashboard.</p>"

  - `boardId` (string, required)
    Board (category) ID this post belongs to
    Example: "507f1f77bcf86cd799439011"

  - `author` (object,null, required)

  - `author.id` (string,null, required)
    Author unique identifier
    Example: "507f1f77bcf86cd799439011"

  - `author.name` (string, required)
    Author display name
    Example: "John Doe"

  - `author.email` (string,null, required)
    Author email (if available)
    Example: "john@example.com"

  - `author.profilePicture` (string,null, required)
    Author profile picture URL
    Example: "https://cdn.example.com/avatars/john.png"

  - `author.type` (string, required)
    Type of user who authored the post
    Enum: "admin", "customer", "guest", "integration", "bot", "lead"

  - `status` (object, required)

  - `status.name` (string, required)
    Display name
    Example: "In Progress"

  - `status.color` (string, required)
    Color for UI display
    Example: "Blue"

  - `status.type` (string, required)
    The workflow stage this status represents
    Enum: "reviewing", "unstarted", "active", "completed", "canceled"

  - `status.isDefault` (boolean, required)
    Whether this is the default status for new posts

  - `tags` (array, required)
    Tags attached to this post
    Example: [{"id":"507f1f77bcf86cd799439011","name":"bug","color":"#FF5722"}]

  - `tags.id` (string, required)
    Tag unique identifier
    Example: "507f1f77bcf86cd799439011"

  - `tags.name` (string, required)
    Tag name
    Example: "bug"

  - `tags.color` (string,null, required)
    Tag color hex code
    Example: "#FF5722"

  - `features` (object, required)

  - `features.commentsEnabled` (boolean, required)
    Whether comments are allowed on this post
    Example: true

  - `upvotes` (number, required)
    Total number of upvotes
    Example: 42

  - `commentCount` (number, required)
    Total number of comments
    Example: 5

  - `inReview` (boolean, required)
    Whether the post is pending moderation review

  - `isPinned` (boolean, required)
    Whether the post is pinned to the top

  - `access` (object, required)

  - `access.userIds` (array, required)
    User IDs explicitly granted access to this post. Empty array means no user-level restrictions (post uses board/org visibility). Non-empty means only these users (plus admins) can see the post.
    Example: []

  - `access.companyExternalIds` (array, required)
    External company IDs explicitly granted access to this post. Empty array means no company-level restrictions. Non-empty means only users belonging to these companies can see the post.
    Example: []

  - `assigneeId` (string,null, required)
    ID of the admin assigned to this post, null if unassigned
    Example: "507f1f77bcf86cd799439013"

  - `eta` (string,null, required)
    Estimated completion time as ISO 8601 timestamp, null if not set
    Example: "2025-01-01T00:00:00.000Z"

  - `customFields` (object, required)
    Custom field values keyed by field ID
    Example: {"cf_priority":"high","cf_effort":3}

  - `createdAt` (string, required)
    ISO 8601 timestamp when created
    Example: "2023-12-12T00:00:00.000Z"

  - `updatedAt` (string, required)
    ISO 8601 timestamp when last modified
    Example: "2023-12-13T00:00:00.000Z"

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "invalid_request"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 400

## Response 404 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "board_not_found"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 404