AiVideoEditor
Empieza gratis
Menú

Referencia de API

Versión de API 2026-11-09 · Descargar YAML de OpenAPI 3.1

La autenticación usa una clave de producto con alcance de espacio de trabajo: Authorization: Bearer pk_v1_…. Las claves llevan scopes explícitos y una lista de cuentas permitidas opcional; nunca pueden crear otras claves ni cambiar la facturación. Todas las mutaciones requieren una cabecera Idempotency-Key; las ediciones y la programación también requieren expectedVersion. Publish y schedule devuelven 202 Accepted con un ID de entrega por destino: 202 nunca afirma que algo se haya publicado. Verifica los resultados mediante GET /posts/{id}, webhooks de cliente o sondeo acotado con backoff. Los errores usan el sobre normalizado del contrato v1: code, message seguro, fieldErrors, destinationErrors, retryable, retryAfterSeconds y requestId. Deliberadamente no existe un código de error de crédito de publicación o de cuota.

Autenticación

Envía una clave de producto del espacio de trabajo como "Authorization: Bearer pk_v1_…". Cada operación indica los permisos requeridos. Consulta autenticación y permisos.

GET /capabilities

Formatos y opciones elegibles para destinos permitidos

Requiere el scope accounts:read.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "accounts"
  ],
  "summary": "Formatos y opciones elegibles para destinos permitidos",
  "description": "Requiere el scope `accounts:read`.",
  "responses": {
    "200": {
      "description": "Capability list",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "capabilities",
              "requestId"
            ],
            "properties": {
              "capabilities": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Capability"
                }
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /accounts

Lista las cuentas de destino visibles para esta clave

Respeta la lista de cuentas permitidas de la clave. Requiere el scope accounts:read.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "accounts"
  ],
  "summary": "Lista las cuentas de destino visibles para esta clave",
  "description": "Respeta la lista de cuentas permitidas de la clave. Requiere el scope `accounts:read`.",
  "parameters": [
    {
      "$ref": "#/components/parameters/cursor"
    },
    {
      "$ref": "#/components/parameters/limit"
    }
  ],
  "responses": {
    "200": {
      "description": "Account page",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "accounts",
              "requestId"
            ],
            "properties": {
              "accounts": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Account"
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /accounts/{id}/tiktok/settings

Lee la configuración verificada del creador de TikTok para una cuenta conectada permitida

Requiere accounts:read y la lista de cuentas permitidas de la clave. Esta lectura nunca suministra el consentimiento humano de publicación.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "accounts"
  ],
  "summary": "Lee la configuración verificada del creador de TikTok para una cuenta conectada permitida",
  "description": "Requiere accounts:read y la lista de cuentas permitidas de la clave. Esta lectura nunca suministra el consentimiento humano de publicación.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Current typed creator settings; a person must confirm choices in the composer",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "settings",
              "humanConfirmationRequired",
              "requestId"
            ],
            "properties": {
              "settings": {
                "$ref": "#/components/schemas/TikTokCreatorSettings"
              },
              "humanConfirmationRequired": {
                "type": "boolean",
                "const": true
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /media/upload-intents

Reserva bytes y devuelve instrucciones de subida directa

Requiere el scope media:write más una Idempotency-Key. Los bytes se suben DIRECTAMENTE al almacenamiento de objetos privado usando las instrucciones devueltas; nunca pasan por esta API. No existe una URL pública permanente para los medios.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "media"
  ],
  "summary": "Reserva bytes y devuelve instrucciones de subida directa",
  "description": "Requiere el scope `media:write` más una Idempotency-Key. Los bytes se suben DIRECTAMENTE al almacenamiento de objetos privado usando las instrucciones devueltas; nunca pasan por esta API. No existe una URL pública permanente para los medios.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UploadIntentRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Upload instructions created",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UploadIntentResponse"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "402": {
      "$ref": "#/components/responses/PaymentRequired"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /media/{id}

Estado y caducidad de los medios (sin URL pública permanente)

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "media"
  ],
  "summary": "Estado y caducidad de los medios (sin URL pública permanente)",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    }
  ],
  "responses": {
    "200": {
      "description": "Media status",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "media",
              "requestId"
            ],
            "properties": {
              "media": {
                "$ref": "#/components/schemas/MediaStatus"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /media/{id}/upload-parts

Renueva de una a 64 URLs PUT multipart en una sesión de subida existente

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "media"
  ],
  "summary": "Renueva de una a 64 URLs PUT multipart en una sesión de subida existente",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "fromPart",
            "toPart"
          ],
          "properties": {
            "fromPart": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000
            },
            "toPart": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Fresh upload URLs; toPart must be at least fromPart and at most fromPart + 63",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "sessionId",
              "parts",
              "requestId"
            ],
            "properties": {
              "sessionId": {
                "type": "string",
                "format": "uuid"
              },
              "requestId": {
                "type": "string"
              },
              "parts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "partNumber",
                    "url",
                    "expiresAt"
                  ],
                  "properties": {
                    "partNumber": {
                      "type": "integer"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /media/{id}/abandon

Abandona una subida incompleta y libera su reserva de almacenamiento

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "media"
  ],
  "summary": "Abandona una subida incompleta y libera su reserva de almacenamiento",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Abandoned; failed external cleanup remains durably queued",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "abandoned",
              "requestId"
            ],
            "properties": {
              "abandoned": {
                "type": "boolean",
                "const": true
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /media/{id}/finalize

Verifica el objeto subido y lo hace utilizable

Requiere el scope media:write más una Idempotency-Key. El servidor verifica tamaño/MIME y firmas acotadas contra la copia FINAL inmutable; las reservas de bytes se liquidan exactamente una vez. Envía solo la identidad de la sesión (más los recibos de partes multipart cuando aplique): el servidor observa todos los metadatos por sí mismo.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "media"
  ],
  "summary": "Verifica el objeto subido y lo hace utilizable",
  "description": "Requiere el scope `media:write` más una Idempotency-Key. El servidor verifica tamaño/MIME y firmas acotadas contra la copia FINAL inmutable; las reservas de bytes se liquidan exactamente una vez. Envía solo la identidad de la sesión (más los recibos de partes multipart cuando aplique): el servidor observa todos los metadatos por sí mismo.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/FinalizeRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Finalized",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "media",
              "requestId"
            ],
            "properties": {
              "media": {
                "$ref": "#/components/schemas/FinalizeResult"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /posts

Crea un borrador

Requiere el scope posts:write más una Idempotency-Key. Los cuerpos se analizan con el DraftInputSchema estricto del contrato v1; las cuentas de destino duplicadas se rechazan. Guardar es permisivo: valida antes de publicar.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "posts"
  ],
  "summary": "Crea un borrador",
  "description": "Requiere el scope `posts:write` más una Idempotency-Key. Los cuerpos se analizan con el DraftInputSchema estricto del contrato v1; las cuentas de destino duplicadas se rechazan. Guardar es permisivo: valida antes de publicar.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/DraftInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Draft created",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "post",
              "requestId"
            ],
            "properties": {
              "post": {
                "$ref": "#/components/schemas/DraftSaveResult"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /posts

Lista las publicaciones

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "posts"
  ],
  "summary": "Lista las publicaciones",
  "parameters": [
    {
      "$ref": "#/components/parameters/cursor"
    },
    {
      "$ref": "#/components/parameters/limit"
    },
    {
      "name": "state",
      "in": "query",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Post page",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "posts",
              "requestId"
            ],
            "properties": {
              "posts": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PostListItem"
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /posts/{id}

Estado agregado y por destino de la publicación

"Aceptado por el proveedor" no es "Publicado". Los enlaces nativos aparecen solo después de un recibo confirmado; la ausencia de permalink no es prueba de fallo.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "posts"
  ],
  "summary": "Estado agregado y por destino de la publicación",
  "description": "\"Aceptado por el proveedor\" no es \"Publicado\". Los enlaces nativos aparecen solo después de un recibo confirmado; la ausencia de permalink no es prueba de fallo.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    }
  ],
  "responses": {
    "200": {
      "description": "Post status",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "post",
              "requestId"
            ],
            "properties": {
              "post": {
                "$ref": "#/components/schemas/PostStatus"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

PATCH /posts/{id}

Edita un borrador (con verificación de versión)

Requiere Idempotency-Key y expectedVersion. Una versión obsoleta devuelve 409 revision_conflict con la versión actual en error.details.currentVersion.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "posts"
  ],
  "summary": "Edita un borrador (con verificación de versión)",
  "description": "Requiere Idempotency-Key y expectedVersion. Una versión obsoleta devuelve 409 revision_conflict con la versión actual en `error.details.currentVersion`.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/DraftUpdateInput"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated draft",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "post",
              "requestId"
            ],
            "properties": {
              "post": {
                "$ref": "#/components/schemas/DraftSaveResult"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /posts/{id}/validate

Validación estructurada por destino (sin mutación)

Devuelve 200 con validation.valid=false cuando los destinos tienen problemas (nunca un estado de error por problemas de contenido).

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "posts"
  ],
  "summary": "Validación estructurada por destino (sin mutación)",
  "description": "Devuelve 200 con `validation.valid=false` cuando los destinos tienen problemas (nunca un estado de error por problemas de contenido).\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "expectedVersion": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Validation result",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "validation",
              "requestId"
            ],
            "properties": {
              "validation": {
                "$ref": "#/components/schemas/ValidationResult"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /posts/{id}/publish

Publicar ahora (202)

Requiere el scope posts:publish más una Idempotency-Key. El expectedVersion opcional aplica la misma garantía de concurrencia optimista que la edición. Devuelve un ID de entrega por destino; nunca afirma Published.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "posts"
  ],
  "summary": "Publicar ahora (202)",
  "description": "Requiere el scope `posts:publish` más una Idempotency-Key. El `expectedVersion` opcional aplica la misma garantía de concurrencia optimista que la edición. Devuelve un ID de entrega por destino; nunca afirma Published.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "expectedVersion": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Accepted for dispatch",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AcceptedOperation"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "402": {
      "$ref": "#/components/responses/PaymentRequired"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /posts/{id}/schedule

Programa la revisión congelada (202)

Requiere el scope posts:publish más Idempotency-Key y expectedVersion. Un único instante para todo el lote; debe ser futuro y estar dentro del horizonte de 90 días (aplicado por el servicio compartido). revisionId debe ser null en V1: seleccionar una revisión arbitraria no está soportado y se rechaza.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "posts"
  ],
  "summary": "Programa la revisión congelada (202)",
  "description": "Requiere el scope `posts:publish` más Idempotency-Key y expectedVersion. Un único instante para todo el lote; debe ser futuro y estar dentro del horizonte de 90 días (aplicado por el servicio compartido). `revisionId` debe ser null en V1: seleccionar una revisión arbitraria no está soportado y se rechaza.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ScheduleRequest"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Scheduled",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AcceptedOperation"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "402": {
      "$ref": "#/components/responses/PaymentRequired"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /deliveries/{id}/cancel

Cancela un trabajo de destino si está seguramente sin reclamar

Requiere el scope posts:publish más Idempotency-Key. Las entregas ya enviadas devuelven 409 too_late_to_cancel con el estado real.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "deliveries"
  ],
  "summary": "Cancela un trabajo de destino si está seguramente sin reclamar",
  "description": "Requiere el scope `posts:publish` más Idempotency-Key. Las entregas ya enviadas devuelven 409 too_late_to_cancel con el estado real.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "responses": {
    "200": {
      "description": "Cancellation result",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "delivery",
              "requestId"
            ],
            "properties": {
              "delivery": {
                "type": "object",
                "required": [
                  "deliveryId",
                  "canceled",
                  "state"
                ],
                "properties": {
                  "deliveryId": {
                    "type": "string"
                  },
                  "canceled": {
                    "type": "boolean"
                  },
                  "state": {
                    "type": "string"
                  }
                }
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /deliveries/{id}/retry

Reintenta un destino con fallo conocido

Requiere el scope posts:publish más Idempotency-Key. Los resultados desconocidos o las entregas exitosas se rechazan: reintentar podría duplicar la publicación.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "deliveries"
  ],
  "summary": "Reintenta un destino con fallo conocido",
  "description": "Requiere el scope `posts:publish` más Idempotency-Key. Los resultados desconocidos o las entregas exitosas se rechazan: reintentar podría duplicar la publicación.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "responses": {
    "200": {
      "description": "Retry accepted",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "delivery",
              "requestId"
            ],
            "properties": {
              "delivery": {
                "type": "object",
                "required": [
                  "deliveryId",
                  "state"
                ],
                "properties": {
                  "deliveryId": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string"
                  }
                }
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /usage

Plan, uso de cuentas/puestos/almacenamiento, actividad e información de tasa

Requiere el scope usage:read. NO contiene ningún contador de publicaciones restantes de ningún tipo: publicar es ilimitado en todos los planes de pago.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "usage"
  ],
  "summary": "Plan, uso de cuentas/puestos/almacenamiento, actividad e información de tasa",
  "description": "Requiere el scope `usage:read`. NO contiene ningún contador de publicaciones restantes de ningún tipo: publicar es ilimitado en todos los planes de pago.\n",
  "responses": {
    "200": {
      "description": "Usage snapshot",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "usage",
              "requestId"
            ],
            "properties": {
              "usage": {
                "$ref": "#/components/schemas/Usage"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /webhooks

Registra un destino de eventos de cliente

Requiere el scope webhooks:manage más Idempotency-Key. Solo HTTPS; la validación SSRF (esquema, credenciales, dirección resuelta por DNS acotada) se ejecuta antes del almacenamiento. El secreto de firma se devuelve solo en la PRIMERA respuesta de creación: una repetición idempotente devuelve el endpoint sin el secreto. La creación también encola un evento de verificación dirigido.

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "webhooks"
  ],
  "summary": "Registra un destino de eventos de cliente",
  "description": "Requiere el scope `webhooks:manage` más Idempotency-Key. Solo HTTPS; la validación SSRF (esquema, credenciales, dirección resuelta por DNS acotada) se ejecuta antes del almacenamiento. El secreto de firma se devuelve solo en la PRIMERA respuesta de creación: una repetición idempotente devuelve el endpoint sin el secreto. La creación también encola un evento de verificación dirigido.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateWebhookRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Endpoint created (secret shown once)",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "webhook",
              "requestId"
            ],
            "properties": {
              "webhook": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEndpoint"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "secret": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Present only on the first successful creation; null on replay."
                      }
                    }
                  }
                ]
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /webhooks

Lista los destinos de eventos (sin secretos)

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "webhooks"
  ],
  "summary": "Lista los destinos de eventos (sin secretos)",
  "responses": {
    "200": {
      "description": "Endpoint list",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "webhooks",
              "requestId"
            ],
            "properties": {
              "webhooks": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

DELETE /webhooks/{id}

Elimina un destino de eventos

Requiere el scope webhooks:manage y una Idempotency-Key (las repeticiones son seguras).

Los detalles de cada operación incluyen parámetros, cuerpos de solicitud, respuestas y referencias a componentes. Las definiciones referenciadas aparecen más abajo.

{
  "tags": [
    "webhooks"
  ],
  "summary": "Elimina un destino de eventos",
  "description": "Requiere el scope `webhooks:manage` y una Idempotency-Key (las repeticiones son seguras).",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "responses": {
    "204": {
      "description": "Deleted",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

Definiciones compartidas

securitySchemes

productKey
{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "pk_v1_… (product key; NOT a Supabase key)"
}

parameters

id
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
cursor
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
limit
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 25
  }
}
idempotencyKey
{
  "name": "Idempotency-Key",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 255
  },
  "description": "Misma clave + mismo cuerpo normalizado repite el resultado registrado; misma clave + cuerpo distinto devuelve 409 idempotency_conflict.\n"
}

headers

requestId
{
  "description": "ID de correlación por solicitud, también devuelto en los sobres de error.",
  "schema": {
    "type": "string"
  }
}
retryAfter
{
  "description": "Segundos hasta la siguiente ventana de límite de tasa.",
  "schema": {
    "type": "integer"
  }
}

responses

Unauthorized
{
  "description": "Clave de producto ausente, mal formada, desconocida, caducada o revocada.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
Forbidden
{
  "description": "La clave carece del scope requerido, o el recurso pertenece a otro espacio de trabajo.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
PaymentRequired
{
  "description": "Problema de derechos (suscripción inactiva, prueba caducada, límite de cuentas/puestos/almacenamiento).",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
NotFound
{
  "description": "El recurso no existe en el espacio de trabajo del solicitante.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
Conflict
{
  "description": "Conflicto de versión/idempotencia/cancelación/consentimiento/estado de entrega.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
Validation
{
  "description": "El cuerpo de la solicitud o el contenido del destino falló la validación.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
RateLimited
{
  "description": "Límite de tasa técnico por espacio de trabajo. Solo control de velocidad: nunca una cuota de publicaciones.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    },
    "Retry-After": {
      "$ref": "#/components/headers/retryAfter"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
ServerError
{
  "description": "5XX seguro (proveedor no disponible o error interno inesperado). Nunca contiene diagnósticos en bruto.",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

schemas

Error
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message",
        "requestId"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "unauthenticated",
            "forbidden_scope",
            "account_not_allowed",
            "account_limit",
            "seat_limit",
            "storage_limit",
            "subscription_inactive",
            "trial_expired",
            "validation_failed",
            "unsupported_format",
            "consent_required",
            "reconnect_required",
            "destination_identity_changed",
            "revision_conflict",
            "idempotency_conflict",
            "too_late_to_cancel",
            "media_expired",
            "media_deleting",
            "rate_limited",
            "provider_unavailable",
            "submission_unknown",
            "destination_conflict",
            "not_found",
            "internal_error"
          ]
        },
        "message": {
          "type": "string"
        },
        "fieldErrors": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "field",
              "code",
              "message"
            ],
            "properties": {
              "field": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        },
        "destinationErrors": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "accountId",
              "code",
              "message"
            ],
            "properties": {
              "accountId": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        },
        "retryable": {
          "type": "boolean"
        },
        "retryAfterSeconds": {
          "type": "integer"
        },
        "details": {
          "type": "object",
          "additionalProperties": true,
          "description": "Machine-readable extras, e.g. currentVersion for revision_conflict."
        },
        "requestId": {
          "type": "string"
        },
        "requiresAction": {
          "type": "object",
          "description": "Session UI handoff for human consent; never contains credentials or grants access.",
          "required": [
            "type",
            "url",
            "accountIds"
          ],
          "properties": {
            "type": {
              "type": "string",
              "const": "human_consent"
            },
            "url": {
              "type": "string",
              "format": "uri-reference"
            },
            "accountIds": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            },
            "workspaceId": {
              "type": "string",
              "format": "uuid",
              "description": "Verified key workspace; the browser must verify membership before switching its selected workspace."
            }
          }
        }
      }
    }
  }
}
Account
{
  "type": "object",
  "required": [
    "id",
    "network",
    "destinationType",
    "displayName",
    "connectionState"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "network": {
      "type": "string",
      "example": "instagram"
    },
    "destinationType": {
      "type": "string",
      "example": "professional_account"
    },
    "displayName": {
      "type": "string"
    },
    "connectionState": {
      "type": "string",
      "example": "connected"
    },
    "capabilityVersion": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}
Capability
{
  "type": "object",
  "required": [
    "accountId",
    "network"
  ],
  "properties": {
    "accountId": {
      "type": "string"
    },
    "network": {
      "type": "string"
    },
    "networkEnabled": {
      "type": "boolean"
    },
    "accountConnected": {
      "type": "boolean"
    },
    "capabilityVersion": {
      "type": [
        "string",
        "null"
      ]
    },
    "formats": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "enum": [
              "text",
              "single_image",
              "image_set",
              "video"
            ]
          },
          "maxMediaCount": {
            "type": "integer"
          },
          "maxBytes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "requiredFields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "eligibleVisibility": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "requiresActionReasons": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "verifiedAt": {
      "type": "string"
    }
  }
}
UploadIntentRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "filename",
    "declaredMime",
    "declaredBytes"
  ],
  "properties": {
    "filename": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "declaredMime": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "example": "image/jpeg"
    },
    "declaredBytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 524288000
    },
    "width": {
      "type": "number",
      "minimum": 0
    },
    "height": {
      "type": "number",
      "minimum": 0
    },
    "durationMs": {
      "type": "number",
      "minimum": 0
    }
  }
}
UploadIntent
{
  "type": "object",
  "required": [
    "assetId",
    "sessionId",
    "objectKey",
    "method",
    "expiresAt",
    "maxBytes"
  ],
  "description": "Los archivos de menos de 50 MB devuelven `method: presigned_put` con una `uploadUrl` de corta duración y las `headers` requeridas. Los archivos de 50 MB o más devuelven `method: multipart_initiated` con `partSizeBytes` y un array `parts` de URLs de partes prefirmadas; sube cada parte y luego finaliza con el recibo ETag de cada parte.\n",
  "properties": {
    "assetId": {
      "type": "string",
      "format": "uuid"
    },
    "sessionId": {
      "type": "string"
    },
    "objectKey": {
      "type": "string",
      "description": "Opaque storage key; never a public URL"
    },
    "method": {
      "type": "string",
      "enum": [
        "presigned_put",
        "multipart_initiated"
      ]
    },
    "uploadUrl": {
      "type": "string",
      "description": "Short-lived; upload bytes directly with the documented method"
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Required request headers for the presigned PUT (e.g. content-type)"
    },
    "partSizeBytes": {
      "type": "integer",
      "description": "Required part size for multipart uploads"
    },
    "parts": {
      "type": "array",
      "description": "Presigned part URLs (multipart_initiated only); request fresh pages when they expire",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "partNumber",
          "url",
          "expiresAt"
        ],
        "properties": {
          "partNumber": {
            "type": "integer",
            "minimum": 1
          },
          "url": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string"
          }
        }
      }
    },
    "expiresAt": {
      "type": "string"
    },
    "maxBytes": {
      "type": "integer"
    }
  }
}
UploadIntentResponse
{
  "allOf": [
    {
      "$ref": "#/components/schemas/UploadIntent"
    },
    {
      "type": "object",
      "required": [
        "requestId"
      ],
      "properties": {
        "requestId": {
          "type": "string"
        }
      }
    }
  ]
}
TikTokCreatorSettings
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "privacyLevels",
    "maxDurationSeconds",
    "allowComments",
    "allowDuet",
    "allowStitch",
    "directPublishingAllowed",
    "inboxAllowed",
    "nativeAccountId"
  ],
  "properties": {
    "privacyLevels": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "PUBLIC_TO_EVERYONE",
          "MUTUAL_FOLLOW_FRIENDS",
          "FOLLOWER_OF_CREATOR",
          "SELF_ONLY"
        ]
      }
    },
    "maxDurationSeconds": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "allowComments": {
      "type": "boolean"
    },
    "allowDuet": {
      "type": "boolean"
    },
    "allowStitch": {
      "type": "boolean"
    },
    "directPublishingAllowed": {
      "type": "boolean"
    },
    "inboxAllowed": {
      "type": "boolean"
    },
    "nativeAccountId": {
      "type": "string"
    },
    "creatorName": {
      "type": "string"
    },
    "creatorAvatarUrl": {
      "type": "string",
      "format": "uri"
    }
  }
}
MediaStatus
{
  "type": "object",
  "required": [
    "id",
    "originalName",
    "mimeType",
    "bytes",
    "uploadState",
    "createdAt",
    "deletionState"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "originalName": {
      "type": "string"
    },
    "mimeType": {
      "type": "string"
    },
    "bytes": {
      "type": "integer"
    },
    "uploadState": {
      "type": "string",
      "enum": [
        "pending",
        "uploading",
        "finalized",
        "rejected"
      ]
    },
    "createdAt": {
      "type": "string"
    },
    "deleteAfter": {
      "type": [
        "string",
        "null"
      ],
      "description": "Dynamic deletion date, or null while kept for scheduled posts."
    },
    "deletionState": {
      "type": "string",
      "enum": [
        "active",
        "deleting",
        "deleted"
      ]
    }
  }
}
FinalizeRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "sessionId"
  ],
  "description": "Los hechos observados declarados por el solicitante (bytes/MIME/checksum) NO se aceptan: el servidor inspecciona por sí mismo la copia FINAL inmutable. Las subidas multipart deben incluir un recibo ETag para cada parte.\n",
  "properties": {
    "sessionId": {
      "type": "string",
      "format": "uuid"
    },
    "multipart": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "parts"
      ],
      "properties": {
        "parts": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "partNumber",
              "etag"
            ],
            "properties": {
              "partNumber": {
                "type": "integer",
                "minimum": 1
              },
              "etag": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          }
        }
      }
    }
  }
}
FinalizeResult
{
  "type": "object",
  "required": [
    "assetId",
    "finalizeOperationId",
    "bytes"
  ],
  "properties": {
    "assetId": {
      "type": "string",
      "format": "uuid"
    },
    "finalizeOperationId": {
      "type": "string"
    },
    "bytes": {
      "type": "integer"
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}
DraftInput
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "caption",
    "destinations"
  ],
  "properties": {
    "caption": {
      "type": "string",
      "maxLength": 70000
    },
    "mediaIds": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "default": []
    },
    "brandFolderId": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "default": null
    },
    "destinations": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "$ref": "#/components/schemas/DraftDestination"
      }
    }
  }
}
DraftDestination
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "accountId",
    "format"
  ],
  "properties": {
    "accountId": {
      "type": "string",
      "format": "uuid"
    },
    "format": {
      "type": "string",
      "enum": [
        "text",
        "single_image",
        "image_set",
        "video"
      ]
    },
    "overrides": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "caption": {
          "type": "string"
        },
        "mediaIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "title": {
          "type": "string"
        },
        "options": {
          "type": "object",
          "additionalProperties": true,
          "description": "Validated against an allowlisted per-network schema; never a raw vendor bag."
        }
      }
    }
  }
}
DraftUpdateInput
{
  "allOf": [
    {
      "$ref": "#/components/schemas/DraftInput"
    },
    {
      "type": "object",
      "required": [
        "expectedVersion"
      ],
      "properties": {
        "expectedVersion": {
          "type": "integer",
          "minimum": 1
        }
      }
    }
  ]
}
DraftSaveResult
{
  "type": "object",
  "required": [
    "postId",
    "version",
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "postId": {
      "type": "string",
      "format": "uuid"
    },
    "version": {
      "type": "integer"
    },
    "createdAt": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    }
  }
}
PostListItem
{
  "type": "object",
  "required": [
    "postId",
    "version",
    "status",
    "updatedAt"
  ],
  "properties": {
    "postId": {
      "type": "string"
    },
    "version": {
      "type": "integer"
    },
    "status": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    }
  }
}
ValidationResult
{
  "type": "object",
  "required": [
    "valid",
    "revisionVersion",
    "destinationResults"
  ],
  "properties": {
    "valid": {
      "type": "boolean"
    },
    "revisionVersion": {
      "type": "integer"
    },
    "destinationResults": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "accountId",
          "valid",
          "requiresAction"
        ],
        "properties": {
          "accountId": {
            "type": "string"
          },
          "valid": {
            "type": "boolean"
          },
          "requiresAction": {
            "type": "boolean",
            "description": "True when the network requires an explicit human/consent step."
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "code",
                "message"
              ],
              "properties": {
                "code": {
                  "type": "string"
                },
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "code",
                "message"
              ],
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}
AcceptedOperation
{
  "type": "object",
  "required": [
    "revisionId",
    "version",
    "operationId",
    "deliveryIds",
    "scheduledAt",
    "timezone",
    "requestId"
  ],
  "properties": {
    "revisionId": {
      "type": "string"
    },
    "version": {
      "type": "integer"
    },
    "operationId": {
      "type": "string"
    },
    "deliveryIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "scheduledAt": {
      "type": "string"
    },
    "timezone": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    },
    "warnings": {
      "type": "array",
      "description": "Non-blocking notices preserved on replay, including key_expires_before_schedule when a key expires at or before dispatch.",
      "items": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
ScheduleRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "scheduledAt",
    "timezone",
    "expectedVersion"
  ],
  "properties": {
    "scheduledAt": {
      "type": "string",
      "format": "date-time",
      "example": "2027-01-12T15:00:00Z"
    },
    "timezone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "example": "America/Indiana/Indianapolis"
    },
    "expectedVersion": {
      "type": "integer",
      "minimum": 1
    },
    "revisionId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Must be null in V1 (schedules the current revision); non-null is rejected."
    }
  }
}
PostStatus
{
  "type": "object",
  "required": [
    "postId",
    "version",
    "status",
    "deliveries"
  ],
  "properties": {
    "postId": {
      "type": "string"
    },
    "version": {
      "type": "integer"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "scheduled",
        "in_progress",
        "published",
        "partially_published",
        "needs_attention",
        "canceled"
      ]
    },
    "deliveries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "accountId": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "dueAt": {
            "type": "string"
          },
          "nativePostUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "Only after a confirmed result."
          },
          "unresolvedExternalOutcome": {
            "type": "boolean"
          },
          "cancelRequestedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "retryCount": {
            "type": "integer"
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}
Usage
{
  "type": "object",
  "description": "No existe ningún contador de publicaciones restantes en este esquema: publicar es ilimitado en todos los planes de pago. Los números de actividad son métricas operativas.\n",
  "required": [
    "plan",
    "accounts",
    "members",
    "storage",
    "scheduling",
    "rateLimit",
    "activity"
  ],
  "properties": {
    "plan": {
      "type": "object",
      "required": [
        "id",
        "label",
        "status"
      ],
      "properties": {
        "id": {
          "type": "string",
          "enum": [
            "trial",
            "creator",
            "studio",
            "operator"
          ]
        },
        "label": {
          "type": "string"
        },
        "version": {
          "type": "integer"
        },
        "interval": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "month",
            "year",
            null
          ]
        },
        "status": {
          "type": "string"
        },
        "paidThrough": {
          "type": [
            "string",
            "null"
          ]
        },
        "trialEndsAt": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "accounts": {
      "type": "object",
      "required": [
        "connected",
        "reserved",
        "maxConnected"
      ],
      "properties": {
        "connected": {
          "type": "integer"
        },
        "reserved": {
          "type": "integer"
        },
        "maxConnected": {
          "type": "integer"
        }
      }
    },
    "members": {
      "type": "object",
      "required": [
        "active",
        "max"
      ],
      "properties": {
        "active": {
          "type": "integer"
        },
        "max": {
          "type": "integer"
        }
      }
    },
    "storage": {
      "type": "object",
      "required": [
        "activeBytes",
        "reservedBytes",
        "maxActiveBytes"
      ],
      "properties": {
        "activeBytes": {
          "type": "integer"
        },
        "reservedBytes": {
          "type": "integer"
        },
        "maxActiveBytes": {
          "type": "integer"
        }
      }
    },
    "scheduling": {
      "type": "object",
      "required": [
        "horizonDays"
      ],
      "properties": {
        "horizonDays": {
          "type": "integer",
          "example": 90
        }
      }
    },
    "rateLimit": {
      "type": "object",
      "required": [
        "requestsPerMinute",
        "note"
      ],
      "properties": {
        "requestsPerMinute": {
          "type": "integer",
          "example": 120
        },
        "note": {
          "type": "string",
          "example": "Technical speed limit: not a posting allowance."
        }
      }
    },
    "activity": {
      "type": "object",
      "description": "Operational metrics only; never an allowance or balance.",
      "required": [
        "deliveriesAttemptedLast30Days",
        "deliveriesPublishedLast30Days"
      ],
      "properties": {
        "deliveriesAttemptedLast30Days": {
          "type": "integer"
        },
        "deliveriesPublishedLast30Days": {
          "type": "integer"
        }
      }
    }
  }
}
CreateWebhookRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "example": "https://example.com/hooks/autoposted"
    },
    "eventTypes": {
      "oneOf": [
        {
          "type": "string",
          "const": "all"
        },
        {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Omit or \"all\" for every event; an array filters by event type."
    },
    "description": {
      "type": "string"
    }
  }
}
WebhookEndpoint
{
  "type": "object",
  "required": [
    "id",
    "url",
    "eventTypes",
    "enabled",
    "createdAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "eventTypes": {
      "oneOf": [
        {
          "type": "string",
          "const": "all"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "enabled": {
      "type": "boolean"
    },
    "verifiedAt": {
      "type": [
        "string",
        "null"
      ]
    },
    "createdAt": {
      "type": "string"
    }
  }
}