SimploAPI

Authorization: Bearer smp_live_…

# Paste your key from Settings → API keys. jq is used below to build and read JSON.
export SIMPLO_API_KEY="smp_live_…"
BASE="https://api.getsimplo.ai/v1"

// quickstart.mjs — Node 18 or later, no packages.
// Run with: SIMPLO_API_KEY=smp_live_… node quickstart.mjs
const BASE = "https://api.getsimplo.ai/v1";

async function simplo(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.SIMPLO_API_KEY}`,
      ...(body !== undefined && { "Content-Type": "application/json" }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const data = res.status === 204 ? null : await res.json();
  if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`);
  return data;
}

const [project] = await simplo("GET", "/projects");

const { ideas } = await simplo("POST", "/generate/captions", {
  projectId: project.id,
  topic: "Our new autumn menu",
  platforms: ["instagram"],
  limit: 3,
});
const idea = ideas[0];

const { imageUrls } = await simplo("POST", "/generate/image", {
  projectId: project.id,
  prompt: idea.imagePrompt,
  format: "instagram-post",
});

// The next whole hour, in UTC.
const HOUR = 60 * 60 * 1000;
const scheduledAt = new Date((Math.floor(Date.now() / HOUR) + 1) * HOUR).toISOString();

const draft = await simplo("POST", "/posts", {
  projectId: project.id,
  caption: `${idea.caption}\n\n${(idea.hashtags ?? []).join(" ")}`,
  imageUrl: imageUrls[0],
  platforms: ["instagram"],
  scheduledAt,
});
console.log(draft.id, draft.status); // draft_scheduled: on the calendar, not sent

const scheduled = await simplo("POST", `/posts/${draft.id}/schedule`, {});
console.log(scheduled.status, scheduled.scheduledAt); // scheduled: goes out at that hour

# .github/workflows/simplo.yml
# Needs a repository secret SIMPLO_API_KEY and a repository variable SIMPLO_PROJECT_ID.
name: Post releases to Simplo

on:
  release:
    types: [published]

jobs:
  post:
    runs-on: ubuntu-latest
    steps:
      - name: Draft a post about the release
        env:
          SIMPLO_API_KEY: ${{ secrets.SIMPLO_API_KEY }}
          PROJECT_ID: ${{ vars.SIMPLO_PROJECT_ID }}
          # Through the environment, never pasted into the script, so quotes
          # and backticks in the release notes can't break it.
          TOPIC: ${{ github.event.release.body || github.event.release.name || github.event.release.tag_name }}
          IDEMPOTENCY_KEY: release-${{ github.event.release.id }}
        run: |
          set -euo pipefail
          BASE=https://api.getsimplo.ai/v1
          api() {
            curl -sS --fail-with-body "$@" \
              -H "Authorization: Bearer $SIMPLO_API_KEY" \
              -H "Content-Type: application/json"
          }

          # 1. A caption about the release notes.
          jq -n --arg projectId "$PROJECT_ID" --arg topic "$TOPIC" \
            '{projectId: $projectId, topic: $topic, platforms: ["instagram"], limit: 1}' \
            | api "$BASE/generate/captions" --data-binary @- > ideas.json \
            || { cat ideas.json >&2; exit 1; }

          # 2. A picture for it.
          jq --arg projectId "$PROJECT_ID" '{projectId: $projectId, prompt: .ideas[0].imagePrompt}' ideas.json \
            | api "$BASE/generate/image" --data-binary @- > image.json \
            || { cat image.json >&2; exit 1; }

          # 3. A draft on the calendar, never sent by itself. Its time is a whole hour (UTC) at
          #    least an hour away, so it is still in the future if you schedule it below.
          AT=$(date -u -d "@$(( ($(date -u +%s) / 3600 + 2) * 3600 ))" +%Y-%m-%dT%H:%M:%SZ)
          jq -n --arg projectId "$PROJECT_ID" --arg at "$AT" \
            --slurpfile ideas ideas.json --slurpfile image image.json \
            '{projectId: $projectId,
              caption: ($ideas[0].ideas[0] | .caption + "\n\n" + (.hashtags // [] | join(" "))),
              imageUrl: $image[0].imageUrls[0],
              platforms: ["instagram"],
              scheduledAt: $at}' \
            | api "$BASE/posts" -H "Idempotency-Key: $IDEMPOTENCY_KEY" --data-binary @- > post.json \
            || { cat post.json >&2; exit 1; }
          jq '{id, status, scheduledAt}' post.json

          # 4. To publish it at that hour instead of leaving a draft, uncomment:
          # api "$BASE/posts/$(jq -r .id post.json)/schedule" -d '{}'

# .github/workflows/simplo-carousel.yml
# Needs a repository secret SIMPLO_API_KEY and a repository variable SIMPLO_PROJECT_ID.
name: Release carousel on Simplo

on:
  release:
    types: [published]

jobs:
  carousel:
    runs-on: ubuntu-latest
    steps:
      - name: Draft a carousel about the release
        env:
          SIMPLO_API_KEY: ${{ secrets.SIMPLO_API_KEY }}
          PROJECT_ID: ${{ vars.SIMPLO_PROJECT_ID }}
          TOPIC: ${{ github.event.release.body || github.event.release.name || github.event.release.tag_name }}
          IDEMPOTENCY_KEY: release-carousel-${{ github.event.release.id }}
        run: |
          set -euo pipefail
          BASE=https://api.getsimplo.ai/v1
          api() {
            curl -sS --fail-with-body "$@" \
              -H "Authorization: Bearer $SIMPLO_API_KEY" \
              -H "Content-Type: application/json"
          }

          # Writes and draws the slides and saves them as a draft. Its time is a whole hour (UTC)
          # at least an hour away, so it is still in the future if you schedule it below.
          AT=$(date -u -d "@$(( ($(date -u +%s) / 3600 + 2) * 3600 ))" +%Y-%m-%dT%H:%M:%SZ)
          jq -n --arg projectId "$PROJECT_ID" --arg topic "$TOPIC" --arg at "$AT" \
            '{projectId: $projectId, topic: $topic, slideCount: 5, scheduledAt: $at}' \
            | api "$BASE/generate/carousel" -H "Idempotency-Key: $IDEMPOTENCY_KEY" --data-binary @- > carousel.json \
            || { cat carousel.json >&2; exit 1; }
          jq '{postId, status, slides: [.slides[].imageUrl]}' carousel.json

          # To publish it at that hour instead of leaving a draft, uncomment:
          # api "$BASE/posts/$(jq -r .postId carousel.json)/schedule" -d '{}'

# 1. Upload the file (MP4 or MOV, up to 100 MB). The type after ; is needed:
#    curl sends an .mp4 as application/octet-stream otherwise. Use video/quicktime for a .mov.
curl -sS "$BASE/videos?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $SIMPLO_API_KEY" \
  -F "[email protected];type=video/mp4" | tee video.json

# 2. A dated draft with the returned video. Its first frame is the cover.
jq --arg projectId "$PROJECT_ID" --arg at "$AT" \
  '{projectId: $projectId, caption: "A minute with our new feature.",
    video: .video, platforms: ["instagram", "facebook"], scheduledAt: $at}' video.json \
| curl -sS "$BASE/posts" \
  -H "Authorization: Bearer $SIMPLO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

2026-11-03T09:00:00-03:00   9 am in São Paulo (12:00 UTC): accepted
2026-11-03T12:00:00Z        the same moment, written in UTC: accepted
2026-11-03T09:00:00         no offset: always 400 validation_error
2026-11-03T09:20:00-03:00   not on the hour: 400 invalid_schedule_time when scheduling (a draft accepts it)
2026-10-01T09:00:00-03:00   in the past: 400 invalid_schedule_time when scheduling (a draft accepts it)

HTTP/1.1 402 Payment Required

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this action.",
    "details": { "allowed": false, "reason": "insufficient_credits", "creditsRemaining": 3, "creditsRequired": 5 }
  }
}

jq -n --arg projectId "$PROJECT_ID" --slurpfile image image.json \
  '{projectId: $projectId, caption: "Fresh bread every morning.",
    imageUrl: $image[0].imageUrls[0], platforms: ["instagram"]}' \
| curl -sS -i "$BASE/posts" \
  -H "Authorization: Bearer $SIMPLO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bread-2026-11-03" \
  --data-binary @-

# Run it again within 24 hours: the same post comes back, not a second one,
# with this header in the answer:
#   Idempotent-Replayed: true

{
  "error": {
    "code": "validation_error",
    "message": "The body is not valid.",
    "details": [
      {
        "code": "invalid_value",
        "values": ["instagram", "tiktok", "facebook"],
        "path": ["platforms", 0],
        "message": "Invalid option: expected one of \"instagram\"|\"tiktok\"|\"facebook\""
      }
    ]
  }
}