{
  "openapi": "3.1.0",
  "info": {
    "title": "wyro API",
    "version": "0.1.0",
    "description": "Post to social media from your agent. Start without signing up with POST /v1/sandbox: the test key simulates every network, is free and lasts 72 hours. Guide for agents: https://wyroapi.com/AGENTS.md. Language of next_step, errors and MCP (es, en or pt): ?lang= in the URL; otherwise the language of the key's workspace; otherwise the Accept-Language header; otherwise Spanish. Field names and paths never change."
  },
  "servers": [
    {
      "url": "https://wyroapi.com"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "paths": {
    "/v1/sandbox": {
      "post": {
        "operationId": "createSandbox",
        "summary": "Create a test key (no sign-up)",
        "description": "Creates an anonymous workspace with simulated accounts and returns a key that lasts 72 hours. Limit: 5 per IP per hour.",
        "security": [],
        "parameters": [
          {
            "name": "client",
            "in": "query",
            "description": "Who creates the key: claude-code, codex, cursor, n8n, cli, curl, web.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "utm_source",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "utm_campaign",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "description": "Workspace language (next_step, errors and MCP). Can also go in the body. Without lang, it comes from the variant prefix (en:home, pt:guia) or from Accept-Language; otherwise Spanish.",
            "schema": {
              "$ref": "#/components/schemas/Lang"
            }
          },
          {
            "name": "Accept-Language",
            "in": "header",
            "description": "If there is no lang and no variant with a language, the first of es, en or pt (honoring q) sets the workspace language. On the other routes it sets the response language when there is no key.",
            "schema": {
              "type": "string",
              "example": "pt-BR,pt;q=0.9"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lang": {
                    "$ref": "#/components/schemas/Lang"
                  },
                  "variant": {
                    "type": "string",
                    "description": "Where the key was created from; an en: or pt: prefix also sets the language."
                  },
                  "client": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Sandbox"
                }
              }
            }
          },
          "429": {
            "description": "Too many keys from this IP (sandbox_limit)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/me": {
      "get": {
        "operationId": "getMe",
        "summary": "Key status",
        "description": "Key mode (sandbox, trial, paid, expired), expiry and the link to connect real accounts.",
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or expired key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/accounts": {
      "get": {
        "operationId": "listAccounts",
        "summary": "List accounts",
        "description": "Accounts available to post to. With a test key they are simulated.",
        "responses": {
          "200": {
            "description": "Accounts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accounts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Account"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or expired key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/posts": {
      "post": {
        "operationId": "createPost",
        "summary": "Publish or schedule",
        "description": "Publishes now or schedules a post to one or more networks. Returns preview_url: show it to the user. Instagram and Pinterest need an image or video; TikTok and YouTube, a video.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePost"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Post created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Post"
                }
              }
            }
          },
          "400": {
            "description": "Invalid data (validation_error, media_required, text_too_long, platform_not_supported)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or expired key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listPosts",
        "summary": "List posts",
        "description": "Newest first. For the next page, repeat the call with cursor = next_cursor; next_cursor is null on the last page.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "next_cursor from the previous page",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Post"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown cursor (validation_error)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/posts/{id}": {
      "get": {
        "operationId": "getPost",
        "summary": "Post status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "post_abc123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Post",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Post"
                }
              }
            }
          },
          "404": {
            "description": "Not found (post_not_found)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "reschedulePost",
        "summary": "Reschedule a post",
        "description": "Moves a scheduled post that hasn't gone out yet to another date.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "post_abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "scheduled_at"
                ],
                "properties": {
                  "scheduled_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Post",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Post"
                }
              }
            }
          },
          "404": {
            "description": "Not found (post_not_found)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "No longer scheduled (post_not_reschedulable)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/connect": {
      "post": {
        "operationId": "connectAccount",
        "summary": "Link to connect a real account",
        "description": "Returns the link the human opens to connect their account. After that, the same key publishes for real.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "platform"
                ],
                "properties": {
                  "platform": {
                    "type": "string",
                    "enum": [
                      "instagram",
                      "facebook",
                      "tiktok",
                      "linkedin",
                      "twitter",
                      "threads",
                      "youtube",
                      "pinterest"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Connect"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Key starting with wyro_sk_"
      }
    },
    "schemas": {
      "Platform": {
        "type": "string",
        "enum": [
          "instagram",
          "facebook",
          "tiktok",
          "linkedin",
          "twitter",
          "threads",
          "youtube",
          "pinterest"
        ]
      },
      "Account": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "acc_abc123"
          },
          "platform": {
            "$ref": "#/components/schemas/Platform"
          },
          "mode": {
            "type": "string",
            "enum": [
              "simulated",
              "real"
            ]
          },
          "username": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "Sandbox": {
        "type": "object",
        "properties": {
          "api_key": {
            "type": "string",
            "description": "Save it: it can't be shown again."
          },
          "mode": {
            "type": "string",
            "enum": [
              "sandbox"
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "workspace_id": {
            "type": "string"
          },
          "accounts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Account"
            }
          },
          "mcp": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              },
              "claude_code": {
                "type": "string"
              }
            }
          },
          "lang": {
            "$ref": "#/components/schemas/Lang"
          },
          "next_step": {
            "type": "string",
            "description": "What to do next, in plain language."
          }
        }
      },
      "Me": {
        "type": "object",
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "sandbox",
              "trial",
              "paid",
              "expired"
            ]
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "key_hint": {
            "type": "string"
          },
          "connect_url": {
            "type": "string"
          },
          "lang": {
            "$ref": "#/components/schemas/Lang"
          },
          "next_step": {
            "type": "string"
          }
        }
      },
      "CreatePost": {
        "type": "object",
        "required": [
          "text"
        ],
        "description": "Send platforms or account_ids.",
        "properties": {
          "text": {
            "type": "string",
            "example": "Hello from my agent"
          },
          "platforms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Platform"
            },
            "example": [
              "instagram",
              "linkedin"
            ]
          },
          "account_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "media": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "image",
                    "video"
                  ]
                },
                "cover_url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Cover of a video (Instagram Reel and thumbnail)."
                }
              }
            }
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time",
            "description": "Without it, the post goes out now."
          },
          "format": {
            "type": "string",
            "enum": [
              "post",
              "story"
            ],
            "default": "post",
            "description": "story: Instagram story, with a single image or video."
          }
        }
      },
      "Post": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "scheduled",
              "published",
              "failed"
            ]
          },
          "simulated": {
            "type": "boolean"
          },
          "text": {
            "type": "string"
          },
          "media": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "scheduled_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "preview_url": {
            "type": "string",
            "description": "Show it to the user."
          },
          "targets": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "account_id": {
                  "type": "string"
                },
                "platform": {
                  "$ref": "#/components/schemas/Platform"
                },
                "simulated": {
                  "type": "boolean"
                },
                "preview_url": {
                  "type": "string"
                }
              }
            }
          },
          "next_step": {
            "type": "string"
          }
        }
      },
      "Connect": {
        "type": "object",
        "properties": {
          "platform": {
            "$ref": "#/components/schemas/Platform"
          },
          "connect_url": {
            "type": "string"
          },
          "next_step": {
            "type": "string"
          }
        }
      },
      "Lang": {
        "type": "string",
        "enum": [
          "es",
          "en",
          "pt"
        ],
        "description": "es: Spanish, en: English, pt: Brazilian Portuguese."
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "missing_api_key",
                  "invalid_api_key",
                  "sandbox_expired",
                  "key_expired",
                  "workspace_suspended",
                  "rate_limited",
                  "sandbox_limit",
                  "validation_error",
                  "platform_not_supported",
                  "no_account_for_platform",
                  "media_required",
                  "text_too_long",
                  "admin_only",
                  "invalid_partner_token",
                  "workspace_not_found",
                  "post_not_cancellable",
                  "account_not_disconnectable",
                  "account_not_found",
                  "post_not_found",
                  "account_disconnected",
                  "provider_error",
                  "post_not_reschedulable",
                  "not_found",
                  "internal_error"
                ]
              },
              "lang": {
                "$ref": "#/components/schemas/Lang",
                "description": "The caller's language; it comes first in message and fix."
              },
              "message": {
                "type": "object",
                "properties": {
                  "es": {
                    "type": "string"
                  },
                  "en": {
                    "type": "string"
                  },
                  "pt": {
                    "type": "string"
                  }
                }
              },
              "fix": {
                "type": "object",
                "properties": {
                  "es": {
                    "type": "string"
                  },
                  "en": {
                    "type": "string"
                  },
                  "pt": {
                    "type": "string"
                  }
                }
              },
              "docs_url": {
                "type": "string"
              },
              "details": {
                "type": "object"
              }
            }
          }
        }
      }
    }
  }
}