Mavenlink Posts API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Kantata OX API Documentation Posts API
  description: Kantata OX's API provides access to the majority of Kantata OX's data model.
  termsOfService: https://www.kantata.com/terms-of-use
  contact:
    name: Kantata OX Support
    url: https://knowledge.kantata.com/hc/en-us
  license:
    name: COPYRIGHT © 2026 Kantata, Inc.
    url: https://www.kantata.com/terms-of-use
  x-logo:
    url: https://theme.zdassets.com/theme_assets/56104/04e93064d309f75d054b8cee885d1ea51e9be8f7.png
    backgroundColor: '#FFFFFF'
    altText: Kantata OX API Documentation
    href: https://developer.kantata.com
servers:
- url: https://api.mavenlink.com/api/v1
tags:
- name: Posts
  description: 'A Post represents a message written by participants in a project that appears in the project. Replies are only

    included if they are directly related to a post. Replies to events, such as Change Orders or Story Created

    Events, are not included.'
paths:
  /posts:
    get:
      summary: Fetching a list of Posts
      description: 'This endpoint returns structured Post objects.

        As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array

        and will be indexed by ID in the `posts` top-level JSON key.

        Please see our Response Format section for more information.'
      operationId: Get Posts
      tags:
      - Posts
      parameters:
      - in: query
        name: created_after
        description: Filter for records created after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
        schema:
          type: string
          format: date-time
      - in: query
        name: created_before
        description: Filter for records created before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
        schema:
          type: string
          format: date-time
      - in: query
        name: external_reference_external_message
        description: Filter the objects based on the external message of their associated external references. This is an exact match.
        schema:
          type: string
      - in: query
        name: external_reference_external_status
        description: Filter by the status of the external object in the external system.
        schema:
          type: string
      - in: query
        name: external_reference_service_model
        description: Filter by the type of the external object this external reference belongs to.
        schema:
          type: string
      - in: query
        name: external_reference_service_model_ref
        description: Filter by the id of the external object this external reference belongs to.
        schema:
          type: integer
          format: int32
      - in: query
        name: external_reference_service_model_refs
        description: Filter for objects that correlate to the specified external object IDs. Provide a comma-separated list of up to 200 external IDs.
        schema:
          type: string
      - in: query
        name: external_reference_service_name
        description: Filter by the name of the provider for integration.
        schema:
          type: string
      - in: query
        name: external_reference_status
        description: Filter by the status of the integration, this can be successful or fail.
        schema:
          type: string
      - in: query
        name: from_archived_workspaces
        description: Also includes posts from archived projects.
        schema:
          type: boolean
          default: false
      - in: query
        name: has_external_references
        description: Filter by whether or not the object has external references.
        schema:
          type: boolean
      - in: query
        name: include
        description: 'Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.

          - `attachments` (Attachments::PostAttachment) - Any attachments associated to the post.

          - `external_references` (ExternalReference) - Includes references to external integrations for this object.

          - `google_documents` (GoogleDocument) - The post''s Google document objects, available in `google_document_ids`; returned in the `google_documents` top-level key.

          - `newest_reply` (Post) - The most recent reply to the post.

          - `newest_reply_user` (User) - The user who made the most recent reply to the post.

          - `recipients` (User) - On private posts, the `recipient_ids` array contains the IDs of recipients, returned in the `users` top-level key.

          - `replies` (Post) - Replies made to this post, returned in the `posts` top-level key. Posts will contain a `reply_ids` array.

          - `story` (Story) - The task (if any) to which the post is linked.

          - `subject` (polymorphic) - When you include this association, posts that are replies will have a `subject_id` key. This references

          their parent post in the `posts` top-level key.

          - `user` (User) - The user who created the post.

          - `workspace` (Workspace) - The project to which this post belongs.'
        schema:
          type: string
      - in: query
        name: only
        description: 'Allows you to request one or more resources directly by ID. Multiple IDs can be supplied

          in a comma separated list, like `GET /api/v1/workspaces.json?only=5,6,7`.'
        schema:
          type: string
      - in: query
        name: order
        description: 'Supply `order` with the name of a valid sort field for the endpoint and a direction.


          Valid values: `newest_reply_at:asc` and `newest_reply_at:desc`.'
        schema:
          type: string
          default: newest_reply_at:desc
      - in: query
        name: page
        schema:
          type: integer
          format: int32
          default: 1
      - in: query
        name: parents_only
        description: Results will only include parent posts (without including replies by themselves).
        schema:
          type: boolean
          default: false
      - in: query
        name: per_page
        schema:
          type: integer
          format: int32
          default: 20
          maximum: 200
      - in: query
        name: private
        description: Only includes posts that are private to the current user.
        schema:
          type: boolean
      - in: query
        name: search
        schema:
          type: string
      - in: query
        name: story_id
        description: Only includes posts from the specified task.
        schema:
          type: integer
          format: int32
      - in: query
        name: story_ids
        description: Filter for posts linked to specific tasks. Provide a comma-separated list of task IDs.
        schema:
          type: string
      - in: query
        name: updated_after
        description: Filter for records updated after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
        schema:
          type: string
          format: date-time
      - in: query
        name: updated_before
        description: Filter for records updated before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
        schema:
          type: string
          format: date-time
      - in: query
        name: without_external_reference_service_name
        description: Exclude by the existence of an external reference with the specified service name.
        schema:
          type: string
      - in: query
        name: workspace_id
        description: Only includes posts from the specified project.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: A list of Posts have been retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    format: int32
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                        format: int32
                      page_count:
                        type: integer
                        format: int32
                      page_number:
                        type: integer
                        format: int32
                      page_size:
                        type: integer
                        format: int32
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        id:
                          type: string
                  posts:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Post'
                  external_references:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/ExternalReference'
                  users:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/User'
                  workspaces:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Workspace'
                  stories:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Story'
                  attachments:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Attachments__PostAttachment'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Forbidden request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Page Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: Service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      summary: Creating a new Post
      description: 'Posts to the Activity Feed of a workspace (project).


        **Bulk Create**


        This endpoint supports bulk creating up to 100 objects. In the request body, set the top-level key to its plural form and place the objects in an array. Example:


        ```

        {

        "posts": [

        {

        "workspace_id": 123,

        "message": "Post"

        },

        {

        "workspace_id": 456,

        "message": "Post"

        }

        ]

        }

        ```


        This endpoint returns structured Post objects.

        As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array

        and will be indexed by ID in the `posts` top-level JSON key.

        Please see our Response Format section for more information.'
      operationId: Create Post
      tags:
      - Posts
      parameters:
      - in: query
        name: include
        description: 'Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.

          - `attachments` (Attachments::PostAttachment) - Any attachments associated to the post.

          - `external_references` (ExternalReference) - Includes references to external integrations for this object.

          - `google_documents` (GoogleDocument) - The post''s Google document objects, available in `google_document_ids`; returned in the `google_documents` top-level key.

          - `newest_reply` (Post) - The most recent reply to the post.

          - `newest_reply_user` (User) - The user who made the most recent reply to the post.

          - `recipients` (User) - On private posts, the `recipient_ids` array contains the IDs of recipients, returned in the `users` top-level key.

          - `replies` (Post) - Replies made to this post, returned in the `posts` top-level key. Posts will contain a `reply_ids` array.

          - `story` (Story) - The task (if any) to which the post is linked.

          - `subject` (polymorphic) - When you include this association, posts that are replies will have a `subject_id` key. This references

          their parent post in the `posts` top-level key.

          - `user` (User) - The user who created the post.

          - `workspace` (Workspace) - The project to which this post belongs.'
        schema:
          type: string
      responses:
        '200':
          description: Post has been created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    format: int32
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                        format: int32
                      page_count:
                        type: integer
                        format: int32
                      page_number:
                        type: integer
                        format: int32
                      page_size:
                        type: integer
                        format: int32
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        id:
                          type: string
                  posts:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Post'
                  external_references:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/ExternalReference'
                  users:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/User'
                  workspaces:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Workspace'
                  stories:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Story'
                  attachments:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Attachments__PostAttachment'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Forbidden request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Page Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: Service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                post:
                  type: object
                  properties:
                    workspace_id:
                      type: integer
                      format: int32
                      description: The ID of the project in which the post will be created.
                    message:
                      type: string
                      description: The content created in the new post.
                    subject_id:
                      type: integer
                      format: int32
                      description: The ID of the item to which the new post is replying (only `required` for replies).
                    subject_type:
                      type: string
                      description: The type of item to which the new post is replying (only `required` for replies). Accepted values are `Post`.
                    story_id:
                      type: integer
                      format: int32
                      description: The ID of the task to which the new post should be linked.
                    recipient_ids:
                      type: array
                      items:
                        type: integer
                        format: int32
                      description: 'An array of User IDs for which the post is visible. These users must be participating in the target

                        project. Including this parameter will make the post private.'
                    attachment_ids:
                      type: array
                      items:
                        type: integer
                        format: int32
                      description: 'An array of PostAttachment IDs to be associated with the post. Create PostAttachments using

                        the attachments endpoint.'
                    google_documents:
                      type: array
                      description: An array of Google document to be associated with the post.
                      items:
                        type: object
                        properties:
                          resource_id:
                            type: string
                            description: A unique identifier for the Google document.
                          access:
                            type: string
                            description: Allowed access to the Google document.
                    backdated_to:
                      type: string
                      format: date-time
                      description: Backdates the post creation date on imports. Defaults to *Now*. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
                  required:
                  - workspace_id
                  - message
        required: true
  /posts/{id}:
    get:
      summary: Fetching a single Post
      description: 'By default, you won''t receive Posts from archived workspaces (and will receive a 404 status

        on the "show" route) unless you provide the `from_archived_workspaces:true` filter.


        This endpoint returns structured Post objects.

        As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array

        and will be indexed by ID in the `posts` top-level JSON key.

        Please see our Response Format section for more information.'
      operationId: Get Post
      tags:
      - Posts
      parameters:
      - in: path
        name: id
        required: true
        description: The ID of the Model.
        schema:
          type: integer
      - in: query
        name: include
        description: 'Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.

          - `attachments` (Attachments::PostAttachment) - Any attachments associated to the post.

          - `external_references` (ExternalReference) - Includes references to external integrations for this object.

          - `google_documents` (GoogleDocument) - The post''s Google document objects, available in `google_document_ids`; returned in the `google_documents` top-level key.

          - `newest_reply` (Post) - The most recent reply to the post.

          - `newest_reply_user` (User) - The user who made the most recent reply to the post.

          - `recipients` (User) - On private posts, the `recipient_ids` array contains the IDs of recipients, returned in the `users` top-level key.

          - `replies` (Post) - Replies made to this post, returned in the `posts` top-level key. Posts will contain a `reply_ids` array.

          - `story` (Story) - The task (if any) to which the post is linked.

          - `subject` (polymorphic) - When you include this association, posts that are replies will have a `subject_id` key. This references

          their parent post in the `posts` top-level key.

          - `user` (User) - The user who created the post.

          - `workspace` (Workspace) - The project to which this post belongs.'
        schema:
          type: string
      responses:
        '200':
          description: The Post has been retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    format: int32
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                        format: int32
                      page_count:
                        type: integer
                        format: int32
                      page_number:
                        type: integer
                        format: int32
                      page_size:
                        type: integer
                        format: int32
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        id:
                          type: string
                  posts:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Post'
                  external_references:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/ExternalReference'
                  users:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/User'
                  workspaces:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Workspace'
                  stories:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Story'
                  attachments:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Attachments__PostAttachment'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Forbidden request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Page Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: Service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    put:
      summary: Updating an existing Post
      description: 'This endpoint returns structured Post objects.

        As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array

        and will be indexed by ID in the `posts` top-level JSON key.

        Please see our Response Format section for more information.'
      operationId: Update Post
      tags:
      - Posts
      parameters:
      - in: path
        name: id
        required: true
        description: The ID of the Model.
        schema:
          type: integer
      - in: query
        name: include
        description: 'Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.

          - `attachments` (Attachments::PostAttachment) - Any attachments associated to the post.

          - `external_references` (ExternalReference) - Includes references to external integrations for this object.

          - `google_documents` (GoogleDocument) - The post''s Google document objects, available in `google_document_ids`; returned in the `google_documents` top-level key.

          - `newest_reply` (Post) - The most recent reply to the post.

          - `newest_reply_user` (User) - The user who made the most recent reply to the post.

          - `recipients` (User) - On private posts, the `recipient_ids` array contains the IDs of recipients, returned in the `users` top-level key.

          - `replies` (Post) - Replies made to this post, returned in the `posts` top-level key. Posts will contain a `reply_ids` array.

          - `story` (Story) - The task (if any) to which the post is linked.

          - `subject` (polymorphic) - When you include this association, posts that are replies will have a `subject_id` key. This references

          their parent post in the `posts` top-level key.

          - `user` (User) - The user who created the post.

          - `workspace` (Workspace) - The project to which this post belongs.'
        schema:
          type: string
      responses:
        '200':
          description: Post has been updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    format: int32
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                        format: int32
                      page_count:
                        type: integer
                        format: int32
                      page_number:
                        type: integer
                        format: int32
                      page_size:
                        type: integer
                        format: int32
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        id:
                          type: string
                  posts:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Post'
                  external_references:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/ExternalReference'
                  users:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/User'
                  workspaces:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Workspace'
                  stories:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Story'
                  attachments:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Attachments__PostAttachment'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Forbidden request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Page Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: Service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                post:
                  type: object
                  properties:
                    message:
                      type: string
                      description: The message content of the post.
                    story_id:
                      type: integer
                      format: int32
                      description: The ID of the task that is linked to the post.
        required: true
    delete:
      summary: Deleting an existing Post
      description: 'The response will contain no content and an HTTP 204 status code if the request was

        successful, or a standard Kantata OX error message explaining why the object could not be deleted.'
      operationId: Delete Post
      tags:
      - Posts
      parameters:
      - in: path
        name: id
        required: true
        description: The ID of the Model.
        schema:
          type: integer
      responses:
        '204':
          description: Post has been deleted.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Forbidden request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Page Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: Service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
components:
  schemas:
    Attachme

# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mavenlink/refs/heads/main/openapi/mavenlink-posts-api-openapi.yml