Autoposting.ai Agents API

openapi: 3.2.0
info:
  title: Autoposting Agents API
  description: 'Schedule, publish, and AI-enhance social content across X, LinkedIn, Instagram, Threads, and YouTube. All responses use the `{ "success": boolean, "data": ... }` envelope. Authenticate with an API key (`Authorization: Bearer sk-social-...` or `x-api-key: sk-social-...`).'
  version: 1.0.0
servers:
- url: https://app.autoposting.ai/api-proxy
  description: Production
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Agents
  description: Create and manage AI agents that autonomously generate and schedule content, trigger runs, inspect outputs, and track statistics.
paths:
  /agents:
    post:
      tags:
      - Agents
      operationId: createAgent
      summary: Create an AI agent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - brandSlug
              - platforms
              properties:
                name:
                  type: string
                  description: Display name for the agent.
                brandSlug:
                  type: string
                  description: Brand the agent posts on behalf of.
                platforms:
                  type: array
                  items:
                    type: string
                    enum:
                    - x
                    - linkedin
                    - instagram
                    - threads
                    - youtube
                    - facebook
                  description: Target platforms.
                schedule:
                  type: string
                  description: 'Cron expression defining when the agent runs (UTC). Example: "0 9 * * 1-5" runs at 9 AM UTC Monday-Friday.'
                knowledgeBaseId:
                  type: string
                  description: ID of the knowledge base the agent draws content ideas from.
                postsPerRun:
                  type: integer
                  default: 1
                  description: Number of posts to generate per run.
                tone:
                  type: string
                  enum:
                  - professional
                  - casual
                  - educational
                  - inspirational
                  - humorous
                  description: Writing tone.
                instructions:
                  type: string
                  description: Custom instructions for the agent (e.g., "Always end with a question to boost engagement").
                autoPublish:
                  type: boolean
                  default: false
                  description: If true, the agent publishes posts immediately. If false, posts are saved as drafts for review.
            example:
              name: Daily LinkedIn Poster
              brandSlug: acme-corp
              platforms:
              - linkedin
              schedule: 0 9 * * 1-5
              knowledgeBaseId: kb_01HXYZ
              postsPerRun: 1
              tone: professional
      responses:
        '200':
          description: Agent created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Agent'
              example:
                success: true
                data:
                  id: agent_01HXYZ
                  name: Daily LinkedIn Poster
                  brandSlug: acme-corp
                  platforms:
                  - linkedin
                  schedule: 0 9 * * 1-5
                  enabled: true
                  autoPublish: false
                  createdAt: '2024-01-01T00:00:00Z'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  message:
                    type: string
              example:
                success: false
                error: unauthorized
                message: Authentication required.
    get:
      tags:
      - Agents
      operationId: listAgents
      summary: List agents
      parameters:
      - name: brandSlug
        in: query
        required: false
        schema:
          type: string
        description: Filter agents by brand.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 100
        description: 'Items per page. Default: 50, max: 100.'
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
        description: 'Items to skip. Default: 0.'
      responses:
        '200':
          description: A list of agents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      agents:
                        type: array
                        items:
                          $ref: '#/components/schemas/Agent'
                      total:
                        type: integer
              example:
                success: true
                data:
                  agents:
                  - id: agent_01HXYZ
                    name: Daily LinkedIn Poster
                    brandSlug: acme-corp
                    platforms:
                    - linkedin
                    enabled: true
                    lastRunAt: '2024-01-10T09:00:00Z'
                    nextRunAt: '2024-01-11T09:00:00Z'
                  total: 1
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  message:
                    type: string
              example:
                success: false
                error: unauthorized
                message: Authentication required.
  /agents/{agentId}:
    get:
      tags:
      - Agents
      operationId: getAgent
      summary: Get an agent
      parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
        description: Agent ID.
        example: agent_01HXYZ
      responses:
        '200':
          description: The agent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Agent'
              example:
                success: true
                data:
                  id: agent_01HXYZ
                  name: Daily LinkedIn Poster
                  brandSlug: acme-corp
                  platforms:
                  - linkedin
                  schedule: 0 9 * * 1-5
                  enabled: true
                  autoPublish: false
                  tone: professional
                  instructions: null
                  knowledgeBaseId: kb_01HXYZ
                  postsPerRun: 1
                  lastRunAt: '2024-01-10T09:00:00Z'
                  nextRunAt: '2024-01-11T09:00:00Z'
                  createdAt: '2024-01-01T00:00:00Z'
                  updatedAt: '2024-01-01T00:00:00Z'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  message:
                    type: string
              example:
                success: false
                error: unauthorized
                message: Authentication required.
    patch:
      tags:
      - Agents
      operationId: updateAgent
      summary: Update an agent
      description: All body fields are optional; only provided fields are updated.
      parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
        description: Agent ID.
        example: agent_01HXYZ
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Updated name.
                schedule:
                  type: string
                  description: Updated cron schedule.
                platforms:
                  type: array
                  items:
                    type: string
                    enum:
                    - x
                    - linkedin
                    - instagram
                    - threads
                    - youtube
                    - facebook
                  description: Updated target platforms.
                tone:
                  type: string
                  enum:
                  - professional
                  - casual
                  - educational
                  - inspirational
                  - humorous
                  description: Updated tone.
                instructions:
                  type: string
                  description: Updated instructions.
                autoPublish:
                  type: boolean
                  description: Updated auto-publish setting.
                postsPerRun:
                  type: integer
                  description: Updated posts per run count.
      responses:
        '200':
          description: The updated agent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Agent'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  message:
                    type: string
              example:
                success: false
                error: unauthorized
                message: Authentication required.
    delete:
      tags:
      - Agents
      operationId: deleteAgent
      summary: Delete an agent
      description: Deleting an agent does not delete its previously generated outputs or posts.
      parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
        description: Agent ID.
        example: agent_01HXYZ
      responses:
        '200':
          description: Agent deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      deleted:
                        type: boolean
              example:
                success: true
                data:
                  id: agent_01HXYZ
                  deleted: true
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  message:
                    type: string
              example:
                success: false
                error: unauthorized
                message: Authentication required.
  /agents/{agentId}/toggle:
    post:
      tags:
      - Agents
      operationId: toggleAgent
      summary: Enable or disable an agent
      description: Enable or disable the agent's scheduled runs.
      parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
        description: Agent ID.
        example: agent_01HXYZ
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - enabled
              properties:
                enabled:
                  type: boolean
                  description: true to enable, false to disable.
            example:
              enabled: false
      responses:
        '200':
          description: Toggle result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Agent'
              example:
                success: true
                data:
                  id: agent_01HXYZ
                  enabled: false
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  message:
                    type: string
              example:
                success: false
                error: unauthorized
                message: Authentication required.
  /agents/{agentId}/run:
    post:
      tags:
      - Agents
      operationId: runAgent
      summary: Trigger an immediate agent run
      description: Bypasses the schedule and triggers an agent run immediately.
      parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
        description: Agent ID.
        example: agent_01HXYZ
      responses:
        '200':
          description: Run queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      runId:
                        type: string
                      status:
                        type: string
                        enum:
                        - queued
                        - running
                        - completed
                        - failed
                      startedAt:
                        type: string
                        format: date-time
              example:
                success: true
                data:
                  runId: run_01HXYZ
                  status: queued
                  startedAt: '2024-01-10T12:00:00Z'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  message:
                    type: string
              example:
                success: false
                error: unauthorized
                message: Authentication required.
  /agents/{agentId}/runs:
    get:
      tags:
      - Agents
      operationId: listAgentRuns
      summary: List agent runs
      parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
        description: Agent ID.
        example: agent_01HXYZ
      responses:
        '200':
          description: A list of agent runs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      runs:
                        type: array
                        items:
                          $ref: '#/components/schemas/AgentRun'
                      total:
                        type: integer
              example:
                success: true
                data:
                  runs:
                  - id: run_01HXYZ
                    agentId: agent_01HXYZ
                    status: completed
                    postsGenerated: 1
                    startedAt: '2024-01-10T09:00:00Z'
                    completedAt: '2024-01-10T09:00:45Z'
                  total: 1
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  message:
                    type: string
              example:
                success: false
                error: unauthorized
                message: Authentication required.
  /agents/{agentId}/runs/{runId}:
    get:
      tags:
      - Agents
      operationId: getAgentRun
      summary: Get a specific run
      parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
        description: Agent ID.
        example: agent_01HXYZ
      - name: runId
        in: path
        required: true
        schema:
          type: string
        description: Run ID.
        example: run_01HXYZ
      responses:
        '200':
          description: The agent run.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/AgentRun'
              example:
                success: true
                data:
                  id: run_01HXYZ
                  agentId: agent_01HXYZ
                  status: completed
                  postsGenerated: 1
                  tokensUsed: 850
                  error: null
                  startedAt: '2024-01-10T09:00:00Z'
                  completedAt: '2024-01-10T09:00:45Z'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  message:
                    type: string
              example:
                success: false
                error: unauthorized
                message: Authentication required.
  /agents/{agentId}/outputs:
    get:
      tags:
      - Agents
      operationId: listAgentOutputs
      summary: List agent outputs
      description: Returns the posts generated by this agent across all runs.
      parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
        description: Agent ID.
        example: agent_01HXYZ
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
        description: 'Items per page. Default: 50.'
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
        description: 'Items to skip. Default: 0.'
      responses:
        '200':
          description: A list of agent outputs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      outputs:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            runId:
                              type: string
                            text:
                              type: string
                            platforms:
                              type: array
                              items:
                                type: string
                                enum:
                                - x
                                - linkedin
                                - instagram
                                - threads
                                - youtube
                                - facebook
                            status:
                              type: string
                            createdAt:
                              type: string
                              format: date-time
                      total:
                        type: integer
              example:
                success: true
                data:
                  outputs:
                  - id: post_01HXYZ
                    runId: run_01HXYZ
                    text: 5 lessons I learned building a SaaS in public...
                    platforms:
                    - linkedin
                    status: draft
                    createdAt: '2024-01-10T09:00:45Z'
                  total: 1
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  message:
                    type: string
              example:
                success: false
                error: unauthorized
                message: Authentication required.
  /agents/{agentId}/stats:
    get:
      tags:
      - Agents
      operationId: getAgentStats
      summary: Get agent statistics
      parameters:
      - name: agentId
        in: path
        required: true
        schema:
          type: string
        description: Agent ID.
        example: agent_01HXYZ
      responses:
        '200':
          description: Agent statistics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      agentId:
                        type: string
                      totalRuns:
                        type: integer
                      successfulRuns:
                        type: integer
                      failedRuns:
                        type: integer
                      totalPostsGenerated:
                        type: integer
                      totalPostsPublished:
                        type: integer
                      averageRunDurationMs:
                        type: integer
              example:
                success: true
                data:
                  agentId: agent_01HXYZ
                  totalRuns: 30
                  successfulRuns: 28
                  failedRuns: 2
                  totalPostsGenerated: 28
                  totalPostsPublished: 24
                  averageRunDurationMs: 38000
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  message:
                    type: string
              example:
                success: false
                error: unauthorized
                message: Authentication required.
components:
  schemas:
    AgentRun:
      type: object
      description: A single execution of an agent.
      properties:
        id:
          type: string
        agentId:
          type: string
        status:
          type: string
          enum:
          - queued
          - running
          - completed
          - failed
        postsGenerated:
          type: integer
        tokensUsed:
          type: integer
        error:
          type:
          - string
          - 'null'
        startedAt:
          type: string
          format: date-time
        completedAt:
          type:
          - string
          - 'null'
          format: date-time
    Agent:
      type: object
      description: An AI agent that autonomously generates and schedules content.
      properties:
        id:
          type: string
        name:
          type: string
        brandSlug:
          type: string
        platforms:
          type: array
          items:
            type: string
            enum:
            - x
            - linkedin
            - instagram
            - threads
            - youtube
            - facebook
        schedule:
          type: string
          description: Cron expression defining when the agent runs (UTC).
        enabled:
          type: boolean
        autoPublish:
          type: boolean
        tone:
          type: string
          enum:
          - professional
          - casual
          - educational
          - inspirational
          - humorous
        instructions:
          type:
          - string
          - 'null'
        knowledgeBaseId:
          type: string
        postsPerRun:
          type: integer
        lastRunAt:
          type:
          - string
          - 'null'
          format: date-time
        nextRunAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key as `Authorization: Bearer sk-social-...`'
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key as `x-api-key: sk-social-...`'