Server API · v1

Server API reference

This reference is rendered from the same OpenAPI 3.1 contract used by the API checks. Download the OpenAPI JSON for Swagger or code generation.

Base URL: https://api.wecloud.biz · Contract version: 1.0.0

Authenticate Server API operations with Authorization: Apisecret <secret> from your backend.

Public errors

Error responses retain HTTP status and include a stable code, safe message, request ID, retryability, and optional details.

Error schema and reusable responses

{
  "schema": {
    "type": "object",
    "required": [
      "error"
    ],
    "properties": {
      "error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "requestId",
          "retryable"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "retryable": {
            "type": "boolean"
          },
          "details": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    }
  },
  "responses": {
    "IdempotencyConflict": {
      "description": "idempotency_key_reused for a changed request, or retryable request_in_progress for a concurrent duplicate",
      "headers": {
        "X-Request-ID": {
          "$ref": "#/components/headers/RequestID"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          },
          "examples": {
            "changedRequest": {
              "value": {
                "error": {
                  "code": "idempotency_key_reused",
                  "message": "Idempotency-Key was used for another request.",
                  "requestId": "00000000-0000-4000-8000-000000000001",
                  "retryable": false
                }
              }
            },
            "inProgress": {
              "value": {
                "error": {
                  "code": "request_in_progress",
                  "message": "Request is still in progress.",
                  "requestId": "00000000-0000-4000-8000-000000000002",
                  "retryable": true
                }
              }
            }
          }
        }
      }
    },
    "BadRequest": {
      "description": "Invalid input, pagination, filter, or missing required Idempotency-Key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "headers": {
        "X-Request-ID": {
          "$ref": "#/components/headers/RequestID"
        }
      }
    },
    "Unauthorized": {
      "description": "Missing, malformed, invalid, or revoked API Secret",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "headers": {
        "X-Request-ID": {
          "$ref": "#/components/headers/RequestID"
        }
      }
    },
    "Forbidden": {
      "description": "Organisation disabled",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "headers": {
        "X-Request-ID": {
          "$ref": "#/components/headers/RequestID"
        }
      }
    },
    "NotFound": {
      "description": "Video, folder, or poster absent from the Secret's Project, or deleted",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "headers": {
        "X-Request-ID": {
          "$ref": "#/components/headers/RequestID"
        }
      }
    },
    "ServerError": {
      "description": "Unexpected failure",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "headers": {
        "X-Request-ID": {
          "$ref": "#/components/headers/RequestID"
        }
      }
    },
    "RateLimited": {
      "description": "Rate limit exceeded; no operation was performed.",
      "headers": {
        "X-Request-ID": {
          "$ref": "#/components/headers/RequestID"
        },
        "RateLimit-Limit": {
          "$ref": "#/components/headers/RateLimit-Limit"
        },
        "RateLimit-Remaining": {
          "$ref": "#/components/headers/RateLimit-Remaining"
        },
        "RateLimit-Reset": {
          "$ref": "#/components/headers/RateLimit-Reset"
        },
        "Retry-After": {
          "$ref": "#/components/headers/Retry-After"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          },
          "example": {
            "error": {
              "code": "rate_limit_exceeded",
              "message": "Rate limit exceeded. Retry later.",
              "requestId": "00000000-0000-4000-8000-000000000001",
              "retryable": true
            }
          }
        }
      }
    }
  }
}