Skip to content
reelspanDocs

Media and analytics

Templates

Save captions, hashtag groups and first comments once and reuse them in posts, for the whole workspace or one profile.

GETapi.reelspan.com/v1/templatesTry it →

Templates are text you post again and again: a caption to start from, a group of hashtags, a first comment with your links. Save them once; in the dashboard the composer's Insert menu puts them in the caption or the first comment, and a bulk CSV can name them.

There are three kinds:

kind What it is
caption Text for the caption.
hashtags A group of hashtags, kept as one line of #tags.
first_comment Text for the first comment.

A template is for the whole workspace, or for one profile when you give profile_username. A profile's posts can use the workspace's templates and its own.

Save a template

curl -X POST https://api.reelspan.com/v1/templates \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "hashtags", "name": "Summer", "body": "summer sun #beach", "profile_username": "my-brand"}'
{
  "success": true,
  "template": {
    "id": "tpl_8c1f…",
    "kind": "hashtags",
    "name": "Summer",
    "body": "#summer #sun #beach",
    "profile_username": "my-brand",
    "created_at": "2026-11-17T10:22:41.000Z",
    "updated_at": "2026-11-17T10:22:41.000Z"
  }
}

The answer is 201.

  • name: up to 80 characters. Names are unique per kind in the workspace, ignoring case: a second caption called “launch” answers 409. A caption and a first comment may share a name.
  • body: up to 10,000 characters.
  • A hashtag group is cleaned up as it is saved: each word gets its #, duplicates and punctuation go, and the tags are joined by spaces. summer sun #beach becomes #summer #sun #beach.
  • A workspace keeps up to 500 templates.

List templates

curl "https://api.reelspan.com/v1/templates?kind=caption&profile_username=my-brand" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"

Answers { "success": true, "templates": [...] }, by kind then name.

  • kind: only this kind. Leave it out for all three.
  • profile_username: only what that profile can use, the workspace's templates and its own. Leave it out for every template.

GET /v1/templates/{id} reads one.

Change or delete a template

Send only what changes. "profile_username": null makes it a workspace template; the kind never changes.

curl -X PATCH https://api.reelspan.com/v1/templates/tpl_8c1f… \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Summer 2027", "body": "#summer #sun #beach #holiday"}'

In a bulk CSV

In the dashboard's bulk upload, a CSV can name templates in three columns instead of writing the text out:

Column What it does
caption_template Uses that caption template when the row has no caption.
hashtags Adds that hashtag group at the end of the caption.
first_comment_template Uses that first comment template when the row has no first comment.

Names are matched ignoring case. A profile's own template wins over a workspace template of the same name. A row naming a template that doesn't exist is left out, and the note above the list says which.

Keys and scopes

Listing and reading need the read scope; saving, changing and deleting need publish. A key limited to some profiles sees the workspace's templates and those profiles' templates, and can only save, change or delete templates of its profiles (403 for a workspace template).

Errors

Status error_code When
400 INVALID_TEMPLATE The name or text is empty or too long, or a hashtag group has no tags.
400 TEMPLATE_LIMIT The workspace already has 500 templates.
403 PROFILE_FORBIDDEN The key can't use that profile, or is limited to some profiles and the template is the workspace's.
404 TEMPLATE_NOT_FOUND No template with that id that the key can see.
404 PROFILE_NOT_FOUND No profile with that username.
409 TEMPLATE_NAME_TAKEN Another template of the same kind has that name.
GETapi.reelspan.com/v1/templatesTry it →

Parameters

  • kindstring · query

    captionhashtagsfirst_comment

  • profile_usernamestring · query

Responses

200 Templates

{
  "success": true,
  "templates": [
    {
      "id": "string",
      "kind": "caption",
      "name": "string",
      "body": "string",
      "profile_username": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ]
}

400 Invalid input

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}

403 Profile not allowed for this key

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}
POSTapi.reelspan.com/v1/templatesTry it →

Request body

application/json

  • kindstringrequired

    captionhashtagsfirst_comment

  • namestringrequired

    Unique per kind in the workspace, ignoring case

  • bodystringrequired
  • profile_usernamestring

    Only for this profile; leave out for the whole workspace

Responses

201 Saved

{
  "success": true,
  "template": {
    "id": "string",
    "kind": "caption",
    "name": "string",
    "body": "string",
    "profile_username": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

400 Invalid input

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}

403 Profile not allowed for this key

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}
GETapi.reelspan.com/v1/templates/{id}Try it →

Parameters

  • idstring · pathrequired

Responses

200 Template

{
  "success": true,
  "template": {
    "id": "string",
    "kind": "caption",
    "name": "string",
    "body": "string",
    "profile_username": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

400 Invalid input

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}

403 Profile not allowed for this key

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}
PATCHapi.reelspan.com/v1/templates/{id}Try it →

Parameters

  • idstring · pathrequired

Request body

application/json

  • namestring
  • bodystring
  • profile_usernamestring

Responses

200 Changed

{
  "success": true,
  "template": {
    "id": "string",
    "kind": "caption",
    "name": "string",
    "body": "string",
    "profile_username": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

400 Invalid input

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}

403 Profile not allowed for this key

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}
DELETEapi.reelspan.com/v1/templates/{id}Try it →

Parameters

  • idstring · pathrequired

Responses

200 Deleted

{
  "success": true,
  "id": "string"
}

400 Invalid input

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}

403 Profile not allowed for this key

{
  "success": false,
  "message": "string",
  "error": "string",
  "error_code": "string"
}

Something unclear or missing? Write to [email protected] and we’ll fix the page.