Postel

Find high-performing public X posts in Postel's index by topic, with source links and stored engagement metrics. No login required. Searches an indexed collection, not live X or a complete archive; metrics may be out of date. Results contain third-party post text.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Topic or keywords; omit to browse high-performing posts",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "minImpressions": {
      "description": "Minimum stored view count (default 10000)",
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647
    },
    "limit": {
      "description": "Number of examples (default 10, maximum 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

List posts for the current organization. Supports filtering by status and pagination.

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Filter posts by status",
      "type": "string",
      "enum": [
        "DRAFT",
        "SCHEDULED",
        "PUBLISHED"
      ]
    },
    "limit": {
      "description": "Number of posts to return (max 50, default 20)",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Get a single post by ID with full details.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "description": "The post ID to retrieve"
    }
  },
  "required": [
    "postId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Save text as a new draft in Postel. Does not publish or schedule. Each call creates a separate draft.

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "maxLength": 10000,
      "description": "The post content (tweet text)"
    },
    "status": {
      "description": "Post status (default: DRAFT)",
      "type": "string",
      "enum": [
        "DRAFT",
        "EDITING"
      ]
    }
  },
  "required": [
    "content"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Update the content or status of a Postel draft. Scheduled and published posts cannot be edited.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "description": "The post ID to update"
    },
    "content": {
      "description": "New content for the post",
      "type": "string",
      "maxLength": 10000
    },
    "status": {
      "description": "New status for the post",
      "type": "string",
      "enum": [
        "DRAFT",
        "EDITING"
      ]
    }
  },
  "required": [
    "postId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Delete a post. A scheduled post's delivery is cancelled first.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "description": "The post ID to delete"
    }
  },
  "required": [
    "postId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Schedule a Postel draft for publishing to the social platform stored on the post. Requires a plan that includes scheduling. scheduledDateTime must be a future UTC ISO-8601 timestamp.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "description": "The post ID to schedule"
    },
    "scheduledDateTime": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "UTC ISO-8601 date string for when to publish (must be in the future)"
    }
  },
  "required": [
    "postId",
    "scheduledDateTime"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Publish a Postel draft immediately to the social platform stored on the post. Requires a plan that includes publishing. A post that is already published cannot be published again.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "description": "The post ID to publish"
    }
  },
  "required": [
    "postId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Generate a new post using AI based on a prompt. Requires usage quota. Returns the generated post.

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 5000,
      "description": "What the post should be about"
    },
    "isThread": {
      "description": "Generate a thread instead of a single post (X only; ignored for LinkedIn)",
      "type": "boolean"
    },
    "platform": {
      "description": "Target platform: \"x\" (default) or \"linkedin\"",
      "type": "string",
      "enum": [
        "x",
        "linkedin"
      ]
    },
    "profileId": {
      "description": "Voice profile ID to use (omit to use default brand voice)",
      "type": "string"
    }
  },
  "required": [
    "prompt"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Suggest refined content for an existing post using AI and specific instructions. Does not save changes. Requires usage quota.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "description": "The post ID to refine"
    },
    "instructions": {
      "type": "string",
      "maxLength": 2000,
      "description": "Instructions for how to refine the post (e.g., 'make it more casual', 'add a call to action')"
    }
  },
  "required": [
    "postId",
    "instructions"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

List all brands (topics) for the current organization. Brands contain background information used for AI post generation.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Get background information sources for a specific brand. These sources are used to inform AI post generation.

{
  "type": "object",
  "properties": {
    "brandId": {
      "type": "string",
      "description": "The brand (topic) ID to get sources for"
    }
  },
  "required": [
    "brandId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Get the X and LinkedIn voice profiles for the current organization. These profiles define the brand voice for AI post generation.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Get the posting schedule template for the current organization. Shows which time slots are configured for each day of the week.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Get the current usage statistics and plan limits for the organization.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}