AdGPT Social Ads Account API

openapi: 3.2.0
info:
  title: AdGPT Social Ads Account API
  version: 1.0.0
  description: '# AdGPT API


    Generate ready-to-publish ad creatives programmatically: full campaigns, single assets (images, videos, UGC presenter and in-action videos, Google ad copy), post-generation edits, ad recreation, and publishing to your own connected social ad accounts — the same engine that powers app.adgpt.com. **Base URL:** `https://api.adgpt.com/api`


    All endpoints live under `/v1`. Responses use a consistent envelope:


    ```json

    { "success": true, "data": { ... }, "message": "..." }

    ```


    Generation is **asynchronous**: a create call returns immediately with an id; you poll a status endpoint until completion (see *Async jobs* below). Every operation that spends credits declares its cost in this reference (`x-credit-cost`). This document is generated from the committed API contract, which a CI gate keeps in sync with the routes and validation on every change — so the reference cannot silently drift from the implementation. ## Authentication


    Authenticate every request with an **API key** in the `Authorization` header:


    ```

    Authorization: Bearer adgpt_... ```


    Create and revoke keys from your account settings at app.adgpt.com (Settings → API Keys). The full key is shown **exactly once** at creation — store it securely. Keys inherit your account''s permissions and spend your account''s credits. **401 responses** carry a machine-readable `code`: `UNAUTHENTICATED` (missing/invalid/revoked/expired key), or for first-party JWTs `TOKEN_EXPIRED` (refresh and retry). Repeated failed authentication from one IP is throttled (`429`, code `TOO_MANY_ATTEMPTS`). Keys never work on the first-party web-app endpoints, and key management itself is only available from the logged-in web app — a leaked key cannot mint further keys. If your organization has turned off publishing, share links and the social ad-account endpoints answer **`403` (`ORG_PUBLISHING_BLOCKED`)**. ### You can only access your own resources


    Every endpoint is scoped to the account that owns the key. A request for a campaign, asset, brand, catalogue or any other resource that belongs to a different account returns **`404` (`RESOURCE_NOT_FOUND`)** — the same response you get for an id that does not exist, so ids cannot be probed for existence. List endpoints only ever return your own account''s resources. Build your integration against the ids you create and receive back from the API. ## Connect from an AI assistant (MCP)


    Everything in this reference is also available as an **MCP (Model Context Protocol) server**, generated from the same API contract — so an AI assistant can drive AdGPT for you instead of you writing HTTP calls. Every operation documented here is an MCP tool with the same inputs, credit costs and async behaviour. **Endpoint:** `https://mcp.adgpt.com/mcp` (Streamable HTTP)


    Connecting needs no credentials. A session starts anonymous; sign in (or register) with the account tool inside the conversation, or seed the identity up front by sending `Authorization: Bearer ` on the `initialize` request. Credits bill the signed-in account. Sessions expire after **30 minutes idle** — sign in again afterwards. ### Connecting a client


    - **Claude (web/desktop):** Customize → Connectors → Add custom connector → paste the endpoint URL. On Team and Enterprise plans an Owner adds it under Organization settings → Connectors. - **Claude Code:** `claude mcp add --transport http adgpt https://mcp.adgpt.com/mcp`

    - **Any other MCP client** that supports remote Streamable HTTP servers: point it at the same URL. ### Discovery


    The server publishes a server card at `https://mcp.adgpt.com/.well-known/mcp/server-card.json` and is listed in the official MCP registry as `com.adgpt/adgpt`. ### Working with the tools


    Start with `adgpt_capabilities` to search the operation surface or describe one operation''s schema.'
servers:
- url: https://api.adgpt.com/api
security:
- bearerAuth: []
tags:
- name: social-ads-account
paths:
  /v1/social/accounts:
    post:
      operationId: post.social-ads-account
      tags:
      - social-ads-account
      summary: Social Ads Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - facebook
                  - google
                  - tiktok
                  - meta
                brand_id:
                  type: integer
                  description: References brands,id.
                ad_account_id: []
                ad_account_name:
                  type: string
                currency:
                  type: string
                token:
                  description: 'Conditionally required (required_if: type,facebook,meta).'
              required:
              - type
              - ad_account_id
              - ad_account_name
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          description: Missing, invalid, expired or revoked credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (see Retry-After header)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-rate-limit:
        class: general
        requests_per_minute: 60
  /v1/social/accounts/check-connection:
    post:
      operationId: post.social-ads-account.check-connection
      tags:
      - social-ads-account
      summary: Check ad-account connection
      description: Whether a brand has a connected ad account of the given type.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                brand_id:
                  type: integer
                type:
                  type: string
                  enum:
                  - facebook
                  - google
                  - tiktok
                  - meta
              required:
              - brand_id
              - type
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '401':
          description: Missing, invalid, expired or revoked credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (see Retry-After header)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-rate-limit:
        class: general
        requests_per_minute: 60
components:
  schemas:
    Envelope:
      type: object
      properties:
        success:
          type: boolean
        data: true
        message:
          type: string
    Error:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        code:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: AdGPT API key (`adgpt_…`), created from your account settings. First-party JWTs are also accepted.