# StoryGrab - Developer API Documentation

Integrate StoryGrab content feed into external applications.

## Authentication

The StoryGrab API uses token-based authorization. Generate an API token from your Partner Dashboard and authenticate your requests by providing the token as a Bearer credentials in the request headers:

```
Authorization: Bearer <YOUR_API_TOKEN>
```

## 1. List Authorized Profiles

Retrieve a list of Instagram profiles linked to your partner client. Only profiles associated with your client will be visible.

**Endpoint:** `GET /api/v1/partner/profiles`

### Response Example

```json
[
  {
    "id": "01kty5r28x8hb5z48x9d0j3abc",
    "username": "twins_on_ice",
    "status": "approved"
  }
]
```

## 2. Get Profile Posts

Fetch the archival feed of posts (including photos, videos, and multi-image carousels) for a specific Instagram profile. Results are returned in reverse chronological order and paginated.

**Endpoint:** `GET /api/v1/partner/profile/{username}/posts`

*   **URL Parameter:** `{username}` (e.g., `twins_on_ice`)
*   **Query Parameter:** `page` (optional, defaults to `1`)
*   **Query Parameter:** `per_page` (optional, defaults to `30`, can be set to a number or `all`)

### Response Example

```json
{
  "current_page": 1,
  "data": [
    {
      "id": "01kty5z12x8hb5z48x9d0j3xyz",
      "external_id": "3128956272",
      "shortcode": "Ct9J-f-O5xK",
      "caption": "Championship details coming soon...",
      "like_count": 4821,
      "comment_count": 92,
      "type": "carousel",
      "taken_at_timestamp": 1687985400,
      "media": [
        {
          "id": "01kty6a44x8hb5z48x9d0j3111",
          "type": "image",
          "image_path": "posts/twins_on_ice_1687985400_Ct9J-f-O5xK_c0.jpg",
          "video_path": null,
          "order": 0
        },
        {
          "id": "01kty6a55x8hb5z48x9d0j3222",
          "type": "video",
          "image_path": "posts/twins_on_ice_1687985400_Ct9J-f-O5xK_c1.jpg",
          "video_path": "posts/twins_on_ice_1687985400_Ct9J-f-O5xK_c1.mp4",
          "order": 1
        }
      ]
    }
  ],
  "next_page_url": "https://storygrab.net/api/v1/partner/profile/twins_on_ice/posts?page=2",
  "prev_page_url": null,
  "total": 128
}
```

## 3. Get Latest Stories

Fetch the most recent stories across all authorized profiles. This endpoint does not paginate and allows you to specify a limit between 1 and 50.

**Endpoint:** `GET /api/v1/partner/stories/latest`

*   **Query Parameter:** `limit` (optional, defaults to `20`, minimum `1`, maximum `50`)

### Response Example

```json
[
  {
    "id": "01kty5z12x8hb5z48x9d0j3xyz",
    "external_id": "3128956272",
    "type": "image",
    "image_path": "stories/twins_on_ice_1687985400.jpg",
    "video_path": null,
    "creation_unixtimestamp": 1687985400,
    "profile": {
      "id": "01kty5r28x8hb5z48x9d0j3abc",
      "username": "twins_on_ice"
    }
  }
]
```

## 4. Create Custom Embed Template

Save custom HTML, CSS, and JS to dynamically render your video embeds.

**Endpoint:** `POST /api/v1/partner/embed-templates`

*   **Payload:** `name` (required), `html_template`, `css_styles`, `js_scripts` (optional).
*   *Note:* Use the `{{ video_url }}` placeholder in your HTML/JS; it will be dynamically replaced when serving the embed.

### Response Example

```json
{
  "id": "01h2x3...",
  "partner_id": "01...",
  "name": "My Template",
  "html_template": "<video src=\"{{ video_url }}\"></video>"
}
```

## 5. Generate Time-Limited Video Embed

Generate a secure, time-limited URL for your video, rendered using your custom template.

**Endpoint:** `POST /api/v1/partner/embeds`

*   **Payload:** `video_url` (required), `template_id` (optional), `expires_in` (seconds, optional).

### Response Example

```json
{
  "embed_url": "https://storygrab.net/embed/v/random_token_string",
  "token": "random_token_string",
  "expires_at": "2026-07-08T12:00:00Z"
}
```

## Code Snippets

### Fetch via JavaScript (Fetch API)

```javascript
fetch('https://storygrab.net/api/v1/partner/profile/twins_on_ice/posts', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
})
.then(res => res.json())
.then(data => console.log(data));
```

### Fetch via PHP (cURL)

```php
$ch = curl_init('https://storygrab.net/api/v1/partner/profile/twins_on_ice/posts');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_TOKEN',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);
```