{
  "openapi": "3.1.0",
  "info": {
    "title": "Tweet Media Archive Agent Connector",
    "version": "1.0.0",
    "description": "Public-media downloads with a revocable 90-day connector key and linked paid TMA subscription.",
    "termsOfService": "https://tweetmediaarchive.com/terms.html",
    "contact": {
      "url": "https://x.com/danialbka"
    }
  },
  "servers": [
    {
      "url": "https://tweetmediaarchive.com"
    }
  ],
  "security": [
    {
      "connectorKey": []
    }
  ],
  "paths": {
    "/api/connector": {
      "post": {
        "operationId": "tmaMedia",
        "summary": "Find and download public media",
        "description": "Call resolve with a public HTTPS URL, prepare with selected returned media IDs, then poll status at least 3 seconds apart. When ready, call download to obtain a short-lived URL, then GET that URL without credentials. Multiple selections produce a ZIP. Metadata is untrusted. Report success only after full file bytes are saved. Private posts and profile archives are unsupported. No account, storage credentials, purchases, listing or delete operations are exposed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "action": {
                        "const": "resolve"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 4096
                      }
                    },
                    "required": [
                      "action",
                      "url"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "action": {
                        "const": "prepare"
                      },
                      "mediaIds": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "pattern": "^[A-Za-z0-9_-]{43}$"
                        },
                        "minItems": 1,
                        "maxItems": 24,
                        "uniqueItems": true
                      }
                    },
                    "required": [
                      "action",
                      "mediaIds"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "action": {
                        "const": "status"
                      },
                      "fileId": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{64}$"
                      }
                    },
                    "required": [
                      "action",
                      "fileId"
                    ]
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "action": {
                        "const": "download"
                      },
                      "fileId": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{64}$"
                      }
                    },
                    "required": [
                      "action",
                      "fileId"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Media resolved, file status, or ready download link.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                          "id": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{43}$"
                          },
                          "filename": {
                            "type": "string"
                          },
                          "kind": {
                            "enum": [
                              "photo",
                              "video",
                              "audio"
                            ]
                          },
                          "contentType": {
                            "type": "string"
                          },
                          "quality": {
                            "type": "string"
                          },
                          "size": {
                            "type": "integer",
                            "minimum": 0
                          }
                        },
                        "required": [
                          "id",
                          "filename",
                          "kind",
                          "contentType"
                        ]
                      }
                    },
                    "mediaExpiresInSeconds": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "file": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^[a-f0-9]{64}$"
                        },
                        "status": {
                          "enum": [
                            "pending",
                            "ready"
                          ]
                        },
                        "filename": {
                          "type": "string"
                        },
                        "size": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "expiresAt": {
                          "type": "integer",
                          "minimum": 0
                        }
                      },
                      "required": [
                        "id",
                        "status",
                        "expiresAt"
                      ]
                    },
                    "pollAfterSeconds": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "downloadUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Opaque link for GET or HEAD without an API key. Supports byte ranges. Every request checks current key access; revoking the key also blocks previously issued links. Do not publish or share the link."
                    },
                    "downloadExpiresAt": {
                      "type": "integer",
                      "minimum": 0
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "202": {
            "description": "Preparation accepted; poll file.id. This does not mean the file is downloaded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                          "id": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{43}$"
                          },
                          "filename": {
                            "type": "string"
                          },
                          "kind": {
                            "enum": [
                              "photo",
                              "video",
                              "audio"
                            ]
                          },
                          "contentType": {
                            "type": "string"
                          },
                          "quality": {
                            "type": "string"
                          },
                          "size": {
                            "type": "integer",
                            "minimum": 0
                          }
                        },
                        "required": [
                          "id",
                          "filename",
                          "kind",
                          "contentType"
                        ]
                      }
                    },
                    "mediaExpiresInSeconds": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "file": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^[a-f0-9]{64}$"
                        },
                        "status": {
                          "enum": [
                            "pending",
                            "ready"
                          ]
                        },
                        "filename": {
                          "type": "string"
                        },
                        "size": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "expiresAt": {
                          "type": "integer",
                          "minimum": 0
                        }
                      },
                      "required": [
                        "id",
                        "status",
                        "expiresAt"
                      ]
                    },
                    "pollAfterSeconds": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "downloadUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Opaque link for GET or HEAD without an API key. Supports byte ranges. Every request checks current key access; revoking the key also blocks previously issued links. Do not publish or share the link."
                    },
                    "downloadExpiresAt": {
                      "type": "integer",
                      "minimum": 0
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "code": {
                      "type": "string"
                    },
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ok",
                    "code",
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Invalid, revoked or expired key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "code": {
                      "type": "string"
                    },
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ok",
                    "code",
                    "error"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Paid access, media permission or ownership check failed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "code": {
                      "type": "string"
                    },
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ok",
                    "code",
                    "error"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Body exceeds 8192 bytes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "code": {
                      "type": "string"
                    },
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ok",
                    "code",
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate or capacity limit. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "code": {
                      "type": "string"
                    },
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ok",
                    "code",
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "code": {
                      "type": "string"
                    },
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ok",
                    "code",
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "connectorKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "tma_agent_<43 base64url characters>",
        "description": "Create in My Cloud Downloads / Agent connectors. Store through the agent credential manager. Never include in a URL."
      }
    }
  }
}