# Create Articles

Created articles are always created as a draft, and need another step to publish them (`PUT` request).

## Create a Basic Article

This example shows how to create and publish an article using the Firstup API. This simulates how a publisher or admin might programmatically push content to the platform.

**Before You Start**

* You have an access token with `content.write` scope. See our [Authorization](/authorization/authenticationandauthorization) guidance.
* You have at least one topic (channel) to publish content to.


**Workflow Overview**

1. Use `GET /v2/channels` to list your available topics (channels) and pass the `channel_id`.
2. Use `POST /v2/content` to create a draft article and link it to the topic by passing the  `channel_id`.
3. Use `PUT /v2/content/{content_id}/publish` to publish your drafted article.


**Endpoints**

GET /v2/channels
POST /v2/content
PUT /v2/content/{content_id}/publish
### Step 1: List Available Topics

Before publishing, get the list of topics to find where your content should go.


```
GET /v2/channels
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Pick a `channel_id` from the response to pass in the next step.

### Step 2: Create a Draft Article

Submit the content as a draft:

* Creating your article as a draft is the default and only way. Publishing this requires another endpoint.
* This gives you a chance to review or edit before publishing.



```
POST /v2/content
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
```


```
{
  "content_type": "article",
  "title": "How to Automate Engagement Campaigns",
  "body": "<p>Engagement starts with relevance...</p>",
  "summary": "Learn how to programmatically publish content using Firstup.",
  "visibility": "private",
  "channels": [
    { "id": 123 } 
  ],
  "featured": false
}
```

The response contains the `content_id` of your draft article. Pass this into the next step.

### Step 3: Publish the Article

Once you're ready, move the article from `draft` to `published`.


```
PUT /v2/content/{content_id}/publish
Authorization: Bearer YOUR_ACCESS_TOKEN
```

The article is now live and visible according to its topic targeting and visibility settings.

## Attach an Image

This example shows how to create an article and attach an image to the body.

* Add up to 10 images per article.
* Images are not resized or hosted. Make sure they are production ready.
* You can update the article's body to explicitly reference or embed the image.


**Before You Start**

* You have an access token with `content.write` scope. See our [Authorization](/authorization/authenticationandauthorization) guidance.
* An image URL hosted on a public CDN or trusted server.
* You have at least one topic (channel) to publish content to.


**Workflow Overview**

1. Use `GET /v2/channels` to list your available topics (channels) and pass the `channel_id`.
2. Use `POST /v2/content` to create a draft article and link it to the topic by passing the  `channel_id`.
3. Use `PUT /v2/content/{content_id}/images` to add an image to your drafted article.
4. Use `PUT /v2/content/{content_id}/publish` to publish your drafted article.


**Endpoints**

GET /v2/channels
POST /v2/content
PUT /v2/content/{content_id}/images
PUT /v2/content/{content_id}/publish
### Step 1: List Available Topics

Before publishing, get the list of topics to find where your content should go.


```
GET /v2/channels
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Pick a `channel_id` from the response to pass in the next step.

### Step 2: Create a Draft Article

Submit the content as a draft:

* Creating your article as a draft is the default and only way. Publishing this requires another endpoint.
* This gives you a chance to review or edit before publishing.



```
POST /v2/content
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
```


```
{
  "content_type": "article",
  "title": "How to Automate Engagement Campaigns",
  "body": "<p>Engagement starts with relevance...</p>",
  "summary": "Learn how to programmatically publish content using Firstup.",
  "visibility": "private",
  "channels": [
    { "id": 123 } 
  ],
  "featured": false
}
```

The response contains the `content_id` of your draft article. Pass this into the next step.

### Step 3: Add an Image to the Article

Now, attach an image using the article’s `content_id`. The image URL must be accessible to Firstup’s servers (e.g., public S3 or CDN link).


```
PUT /v2/content/{content_id}/images
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "image_url": "https://cdn.example.com/images/secure-api-guide.png"
}
```

If successful, the image is now linked to the article and will be included in the rendered view.

### Optional: Add metadata

Optionally add metadata fields. Examples:

* `featured: true`
* `featured_label: "Editor’s Pick"`


### Step 4: Publish

Once you're ready, move the article from `draft` to `published`.


```
PUT /v2/content/{content_id}/publish
Authorization: Bearer YOUR_ACCESS_TOKEN
```

The article is now live and visible according to its topic targeting and visibility settings.

## Attach a Video

This example shows how to create an article and attach a video to the body.

* You can add multiple videos, but only one at a time.
* Videos are not resized—optimize them for web streaming.
* Use `caption` and `preview_image_url` for accessibility and visual polish.


**Before You Start**

* You have an access token with `content.write` scope. See our [Authorization](/authorization/authenticationandauthorization) guidance.
* A public video URL (e.g., MP4 or embed-safe platform).
* You have at least one topic (channel) to publish content to.


**Workflow Overview**

1. Use `GET /v2/channels` to list your available topics (channels) and pass the `channel_id`.
2. Use `POST /v2/content` to create a draft article and link it to the topic by passing the  `channel_id`.
3. Use `PUT /v2/content/{content_id}/videos` to add a video to your drafted article.
4. Use `PUT /v2/content/{content_id}/publish` to publish your drafted article.


**Endpoints**

GET /v2/channels
POST /v2/content
PUT /v2/content/{content_id}/videos
PUT /v2/content/{content_id}/publish
### Step 1: List Available Topics

Before publishing, get the list of topics to find where your content should go.


```
GET /v2/channels
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Pick a `channel_id` from the response to pass in the next step.

### Step 2: Create a Draft Article

Submit the content as a draft:

* Creating your article as a draft is the default and only way. Publishing this requires another endpoint.
* This gives you a chance to review or edit before publishing.



```
POST /v2/content
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
```


```
{
  "content_type": "article",
  "title": "How to Automate Engagement Campaigns",
  "body": "<p>Engagement starts with relevance...</p>",
  "summary": "Learn how to programmatically publish content using Firstup.",
  "visibility": "private",
  "channels": [
    { "id": 123 } 
  ],
  "featured": false
}
```

The response contains the `content_id` of your draft article. Pass this into the next step.

### Step 3: Add a Video to the Article

Now, attach a video using the article’s `content_id`.


```
PUT /v2/content/{content_id}/videos
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "video_url": "https://cdn.example.com/videos/ceo-interview.mp4",
  "caption": "CEO Interview: Leading in 2025",
  "preview_image_url": "https://cdn.example.com/images/ceo-video-thumbnail.jpg"
}
```

The response includes an embed_html snippet, which can be added to the article body if desired.

### Optional: Embed

If you want control over where the video appears in the article, insert the embed_html into the body:


```
PUT /v2/content/{content_id}
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "body": "<p>Watch our CEO talk about leadership:</p><iframe src='...'></iframe>"
}
```

### Step 4: Publish

Once you're ready, move the article from `draft` to `published`.


```
PUT /v2/content/{content_id}/publish
Authorization: Bearer YOUR_ACCESS_TOKEN
```

The article is now live and visible according to its topic targeting and visibility settings.