Quickstart

This guide uses Instagram. The steps for X and YouTube are the same. Replace instagram with x or youtube in each path. In step 3, send X status URLs or YouTube URLs.

1. Create a connect link

curl --request POST "https://api.clipstake.com/v1/instagram/connect-links" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "external_user_id": "customer_8f3a2c19",
    "redirect_uri": "https://your-app.example/connected",
    "metadata": { "plan": "pro" }
  }'

Send the user to the returned url. Store the returned cl_ ID in the user’s browser session.

For X, send the same body to POST /v1/x/connect-links. The user signs in with X and approves access. For YouTube, send it to POST /v1/youtube/connect-links. The user signs in with YouTube and picks a channel.

2. Verify the result

After the redirect, compare connect_id with the stored cl_ ID. Then read the result from your server:

curl "https://api.clipstake.com/v1/instagram/connect-links/$CONNECT_LINK_ID" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY"

Use account.id from a successful result. Do not trust status or account data from the redirect query.

3. Add tracked media

A connect link does not need a project. A connected account belongs to the workspace, so every project can use it. Tracked media belongs to one project, so this step needs a project ID.

Get a project ID

curl "https://api.clipstake.com/v1/projects" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY"

Store a returned prj_ ID.

Add the media

curl --request POST "https://api.clipstake.com/v1/instagram/submissions" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "prj_5f9c0a1b2c3d4e5f60718293",
    "account_id": "acct_3f9c0a1b2c3d4e5f60718293",
    "items": [
      {
        "url": "https://www.instagram.com/p/C9x4AbCdEfG/",
        "metadata": { "campaign": "fall" }
      }
    ]
  }'

Each result contains url, status, and submission. Store submission.id when it is present.

For X, send the request to POST /v1/x/submissions with an X account ID. Use status URLs such as https://x.com/acmestudio/status/1834567890123456789. We accept only videos that the connected account published. See Tracking media.

For YouTube, send the request to POST /v1/youtube/submissions with a YouTube account ID. Use URLs such as https://www.youtube.com/watch?v=aqz-KE-bpKQ. We accept only tracked media that the connected channel published. See Tracking media.

4. Read one item

curl "https://api.clipstake.com/v1/instagram/submissions/sub_4f9c0a1b2c3d4e5f60718293" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY"

Per-ID submission operations do not take project_id. The sub_ ID identifies the resource, and the API key supplies the workspace boundary.

Getting Started

API Reference

Developer Guides

1. Create a connect link

2. Verify the result

3. Add tracked media

Get a project ID

Add the media

4. Read one item

​1. Create a connect link

​2. Verify the result

​3. Add tracked media

​Get a project ID

​Add the media

​4. Read one item

1. Create a connect link

2. Verify the result

3. Add tracked media

Get a project ID

Add the media

4. Read one item