Docs menuSkills

Skills

GET /api/v1/skills

Every skill of the user, in their order (a new user starts with Postory's six): id, slug, name, kind, auto_apply, description and instructions in full — to apply one to a text, follow its instructions. Free.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Example

Request
curl https://postory.io/api/v1/skills \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "skills": [
    {
      "id": "<skill_id>",
      "slug": "launch-voice",
      "name": "Launch voice",
      "kind": "general",
      "auto_apply": true,
      "description": "Use when the request is a product launch post.",
      "instructions": "Lead with the date and what ships. One short sentence per line. No hashtags."
    }
  ],
  "count": 1,
  "limit": 50,
  "skills_url": "https://postory.io/settings/skills",
  "acting_as": {"postory": "[email protected]", "plan": "free"}
}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

POST /api/v1/skills

Create a skill (50 at most: 409 conflict with limit; a slug the user already has: 409 conflict with slug). Idempotency-Key replays the first answer for 24 hours, so a retry makes no second skill.

  • Scopepostory:drafts
  • Limit classWRITE
  • Success201

Parameters

NameInTypeDescription
Idempotency-Keyheaderstring

Any unique string (1-255 characters). The first answer for this key is replayed for 24 hours (Idempotent-Replayed: true) without running anything again; the same key with a different request is 409 idempotency_conflict.

Up to 255 characters

Request body

FieldTypeDescription
auto_applyboolean

Postory's own chat applies it on its own when the description fits (default true).

descriptionrequiredstring

When it applies: Postory's own chat applies an auto_apply skill when this fits the request.

Up to 300 characters
instructionsrequiredstring

The instructions themselves.

Up to 8000 characters
kind"general" | "image"

general (text and images) or image (images only). Default general.

namerequiredstring

What the user calls it.

Up to 80 characters
slugstring

Kebab-case (hook-first), unique among the user's skills. Omitted on create: from the name.

Up to 65 characters

Example

Request
curl https://postory.io/api/v1/skills \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "<description>",
    "instructions": "<instructions>",
    "name": "<name>"
  }'
Response 201
{
  "skill": {
    "id": "<skill_id>",
    "slug": "launch-voice",
    "name": "Launch voice",
    "kind": "general",
    "auto_apply": true,
    "description": "Use when the request is a product launch post.",
    "instructions": "Lead with the date and what ships. One short sentence per line. No hashtags."
  },
  "created": true,
  "skills_url": "https://postory.io/settings/skills",
  "acting_as": {"postory": "[email protected]", "plan": "free"}
}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

409

The state does not allow it now (already scheduled, changed, needs a choice…); branch on code

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

GET /api/v1/skills/{skill}

One skill by its id or slug, with the same fields. 404 not_found lists the user's skills (id, slug, name). Free.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
skillrequiredpathstring

A skill's id from GET /skills, or its slug.

Up to 65 characters

Example

Request
curl "https://postory.io/api/v1/skills/<skill>" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "skill": {
    "id": "<skill_id>",
    "slug": "launch-voice",
    "name": "Launch voice",
    "kind": "general",
    "auto_apply": true,
    "description": "Use when the request is a product launch post.",
    "instructions": "Lead with the date and what ships. One short sentence per line. No hashtags."
  },
  "skills_url": "https://postory.io/settings/skills",
  "acting_as": {"postory": "[email protected]", "plan": "free"}
}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

PATCH /api/v1/skills/{skill}

Change a skill's name, slug, description, instructions, kind or auto_apply; only what is sent changes.

  • Scopepostory:drafts
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
skillrequiredpathstring

A skill's id from GET /skills, or its slug.

Up to 65 characters

Request body

FieldTypeDescription
auto_applyboolean

Postory's own chat applies it on its own when the description fits (default true).

descriptionstring

When it applies: Postory's own chat applies an auto_apply skill when this fits the request.

Up to 300 characters
instructionsstring

The instructions themselves.

Up to 8000 characters
kind"general" | "image"

general (text and images) or image (images only).

namestring

What the user calls it.

Up to 80 characters
slugstring

Kebab-case (hook-first), unique among the user's skills. Omitted on create: from the name.

Up to 65 characters

Example

Request
curl -X PATCH "https://postory.io/api/v1/skills/<skill>" \
  -H "Authorization: Bearer $POSTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_apply": false}'
Response 200
{
  "skill": {
    "id": "<skill_id>",
    "slug": "launch-voice",
    "name": "Launch voice",
    "kind": "general",
    "auto_apply": false,
    "description": "Use when the request is a product launch post.",
    "instructions": "Lead with the date and what ships. One short sentence per line. No hashtags."
  },
  "created": false,
  "skills_url": "https://postory.io/settings/skills",
  "acting_as": {"postory": "[email protected]", "plan": "free"}
}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

409

The state does not allow it now (already scheduled, changed, needs a choice…); branch on code

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

DELETE /api/v1/skills/{skill}

Delete a skill, permanently.

  • Scopepostory:drafts
  • Limit classDELETE
  • Success200

Parameters

NameInTypeDescription
skillrequiredpathstring

A skill's id from GET /skills, or its slug.

Up to 65 characters

Example

Request
curl -X DELETE "https://postory.io/api/v1/skills/<skill>" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "id": "<skill_id>",
  "slug": "launch-voice",
  "name": "Launch voice",
  "deleted": true,
  "acting_as": {"postory": "[email protected]", "plan": "free"}
}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

422

A request parameter is not valid

429

Rate limit spent; see Retry-After