> ## Documentation Index
> Fetch the complete documentation index at: https://dev.magicpost.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Posts

> List, fetch, create, update your posts.

## GET /api/v1/posts

List your posts by lifecycle status.

**Query params**

| Param | Type | Default | Values |
| - | - | - | - |
| `status` | string | `scheduled` | `draft`, `scheduled`, `published` |
| `limit` | int | `20` | Clamped 1–100 |
| `offset` | int | `0` | Pagination |

```bash theme={null}
curl "https://api.magicpost.in/api/v1/posts?status=scheduled&limit=10" \
  -H "Authorization: Bearer mp_xxx"
```

**Response**

```json theme={null}
{
  "status": "scheduled",
  "limit": 10,
  "offset": 0,
  "posts": [
    {
      "id": "uuid",
      "post_content": "Multiple\n\nline post.",
      "created_at": "2026-05-12T10:00:00Z",
      "date_post": "2026-05-20",
      "hour_post": "14:00",
      "schedule_date": "2026-05-20T12:00:00Z",
      "schedule_timezone": "Europe/Paris",
      "planified_post": true,
      "published_post": false,
      "linked_in_url_post": null,
      "word_count": 152,
      "type": "Actionable",
      "category": "Education",
      "approved": null
    }
  ]
}
```

## GET /api/v1/posts/\<post\_id>

Fetch one post in full. 404 if not owned by you.

```bash theme={null}
curl https://api.magicpost.in/api/v1/posts/uuid \
  -H "Authorization: Bearer mp_xxx"
```

**Response**

```json theme={null}
{
  "post": { "id": "uuid", "post_content": "...", "...": "full post record" },
  "publication": {
    "state": "failed",
    "scheduled_at": "2026-09-10T12:30:00+00:00",
    "published_at": null,
    "linkedin_url": null,
    "error": {
      "message": "Response error, code 422: {\"message\":\"ERROR :: /content/media/title :: ...\"}",
      "linkedin_status": 422,
      "linkedin_body": "{\"message\":\"ERROR :: /content/media/title :: ...\"}"
    }
  },
  "scheduled_comments": [
    {
      "comment_id": "uuid",
      "text": "Link in the first comment: https://...",
      "minutes_after": 1,
      "state": null,
      "publish_at": null,
      "comment_url": null,
      "is_draft": false
    }
  ]
}
```

`publication.state` is one of `draft`, `scheduled`, `publishing`, `retrying`,
`published`, `failed`, `missed` (the scheduled time passed by more than 10
minutes without publication: the post will not go out on its own, reschedule
it). `error` is set only on `failed` and `retrying`;
`linkedin_status` and `linkedin_body` are LinkedIn's own answer when LinkedIn
refused the post (they are `null` for other errors, e.g. an expired token).
Check it right after a scheduled time to fix and republish without waiting
for the failure email. `scheduled_comments` lists the comments armed on the
post (see [Comments, AI score and ideas](https://dev.magicpost.in/api-reference/content.md)).

## POST /api/v1/posts

Create a draft post.

**Body**

```json theme={null}
{ "content": "Hello LinkedIn world\n\nThis is line 2." }
```

* `content` (required) — post text. Line breaks (`\n`) are preserved verbatim
  and rendered on LinkedIn.

> [!WARNING]
>
> This REST endpoint creates text-only drafts. MCP clients that support chat file
> references can then call `attach_media_to_post`; otherwise add images, videos,
> polls and `@mentions` from the MagicPost web UI.

**Response** (HTTP 201)

```json theme={null}
{ "success": true, "post_id": "new-uuid", "created": true }
```

## PATCH /api/v1/posts/\<post\_id>

Update the content of an existing post.

**Body**

```json theme={null}
{ "content": "Updated text." }
```

**Response**

```json theme={null}
{ "success": true, "post_id": "uuid", "created": false }
```

Returns 404 if you don't own the post (IDOR guard).

## POST /api/v1/org/members/\<member\_user\_id>/posts

Create a draft owned by a member of the caller's organisation. The caller must
be an organisation `super_admin`, and the target member must still belong to
the same organisation.

```bash theme={null}
curl -X POST \
  https://api.magicpost.in/api/v1/org/members/member-uuid/posts \
  -H "Authorization: Bearer mp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"content":"A post drafted for this team member."}'
```

**Response** (HTTP 201)

```json theme={null}
{
  "success": true,
  "post_id": "new-post-uuid",
  "member_user_id": "member-uuid",
  "created": true
}
```

MCP clients should use `create_member_post`. To attach media, pass both the
returned `post_id` and the same `member_user_id` to the appropriate media
tool, then call `schedule_member_post`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.