{
  "openapi": "3.1.0",
  "info": {
    "title": "Zaps Agentic API",
    "version": "2.0.0",
    "description": "Turn photos and a sentence into finished social-media designs. One call finds matching templates, renders each with the supplied photos, and returns the finished images."
  },
  "servers": [
    {
      "url": "https://api.zaps.design"
    }
  ],
  "x-service-info": {
    "categories": [
      "media",
      "developer-tools"
    ],
    "docs": {
      "homepage": "https://zaps.design/llms.txt",
      "llms": "https://zaps.design/llms.txt",
      "apiReference": "https://zaps.design/openapi.json"
    }
  },
  "paths": {
    "/api/v1/agentic/designs": {
      "post": {
        "operationId": "createDesigns",
        "summary": "Turn photos and a brief into finished designs",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brief"
                ],
                "properties": {
                  "brief": {
                    "type": "string",
                    "description": "What the finished piece is for, in a sentence."
                  },
                  "images": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Publicly reachable image urls, in placement order."
                  },
                  "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "default": 5
                  },
                  "segment": {
                    "type": "string",
                    "description": "Optional shape filter: story, carousel or invite."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Finished designs, each with an image url and an editor link"
          },
          "401": {
            "description": "Missing, unknown or revoked API key"
          },
          "402": {
            "description": "Payment Required — the agentic token balance is empty"
          }
        }
      }
    },
    "/api/v1/agentic/search": {
      "post": {
        "operationId": "searchTemplates",
        "summary": "Search templates by describing the design you want",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "What the design is for, in plain words."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 25,
                    "default": 5
                  },
                  "segment": {
                    "type": "string",
                    "description": "Optional shape filter: story, carousel or invite."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked templates, each with the coverId fill takes and an editor link"
          },
          "401": {
            "description": "Missing, unknown or revoked API key"
          }
        }
      }
    },
    "/api/v1/agentic/fill": {
      "post": {
        "operationId": "fillTemplate",
        "summary": "Render one template with your images",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Give either a coverId from a search hit, or a scene url if you already hold one.",
                "properties": {
                  "coverId": {
                    "type": "string",
                    "description": "coverId from a search result."
                  },
                  "scene": {
                    "type": "string",
                    "description": "Scene url, an alternative to coverId."
                  },
                  "images": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The rendered design"
          },
          "400": {
            "description": "That template cannot be rendered — it is a sticker or a font, not a template"
          },
          "401": {
            "description": "Missing, unknown or revoked API key"
          },
          "402": {
            "description": "Payment Required — the agentic token balance is empty"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A Zaps API key (prefix zak_) or an OAuth access token."
      }
    }
  }
}