{
  "openapi": "3.1.0",
  "info": {
    "title": "InfinityLooper API",
    "version": "1.0.0",
    "summary": "Search free looping video backgrounds and download them with an API key.",
    "description": "Search and browse the catalogue with no key. Downloads need an API key from your account page (Google sign-in) and use the same download allowance as your account on the website; scripts and agents may download in bulk within it. A loop the account already downloaded in the rolling window is free to download again. GET /me reports what is left. Errors are RFC 9457 problem details. A step by step guide with copyable examples is at https://infinitylooper.com/developers.md.",
    "termsOfService": "https://infinitylooper.com/terms",
    "contact": {
      "name": "InfinityLooper support",
      "url": "https://infinitylooper.com/help"
    },
    "license": {
      "name": "InfinityLooper loop licence",
      "url": "https://infinitylooper.com/terms#licence"
    }
  },
  "externalDocs": {
    "description": "Developer guide",
    "url": "https://infinitylooper.com/developers"
  },
  "servers": [
    {
      "url": "https://infinitylooper.com/api/v1"
    }
  ],
  "tags": [
    {
      "name": "Catalogue",
      "description": "Open, no key needed"
    },
    {
      "name": "Downloads",
      "description": "Needs an API key"
    }
  ],
  "paths": {
    "/loops": {
      "get": {
        "operationId": "searchLoops",
        "tags": [
          "Catalogue"
        ],
        "summary": "Search and filter loops",
        "description": "Every word in q must match the title, tags, themes or description. Title matches rank first. Without q, loops come in id order.",
        "security": [],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search words, ranked like the search box on the site: spelling variants (cosy, cozy), synonyms (galaxy, space), plurals and typos are understood. A word no loop matches is set aside and reported in search.dropped.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "theme",
            "in": "query",
            "description": "A theme id from GET /themes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "orientation",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "landscape",
                "vertical"
              ]
            }
          },
          {
            "name": "min_height",
            "in": "query",
            "description": "Smallest frame height in pixels. For landscape loops 1080 is Full HD and 2160 is 4K; vertical loops are taller than they are wide.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "has_audio",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "max_duration",
            "in": "query",
            "description": "Longest loop length in seconds, inclusive.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "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": "A page of loops",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoopPage"
                },
                "example": {
                  "data": [
                    {
                      "id": "IL-AB-0016",
                      "slug": "fox-sleeping-by-a-snowy-fireplace",
                      "title": "Fox sleeping by a snowy fireplace animated background",
                      "url": "https://infinitylooper.com/free/animated-backgrounds/fox-sleeping-by-a-snowy-fireplace",
                      "description": "A fox sleeps beside a fireplace with snow-covered trees outside. A silent 10-second 1080p loop, 3.6 MB.",
                      "best_for": [
                        "TV ambience",
                        "Stream scene in OBS or Streamlabs"
                      ],
                      "tags": [
                        "fox",
                        "fireplace",
                        "snow",
                        "winter"
                      ],
                      "themes": [
                        "snow",
                        "fireplace",
                        "cute-animals"
                      ],
                      "preview_url": "https://infinitylooper.com/previews/v4/IL-AB-0016.mp4",
                      "poster_url": "https://infinitylooper.com/free/posters/hd/IL-AB-0016-640.webp",
                      "file": {
                        "width": 1916,
                        "height": 1080,
                        "resolution": "1916 x 1080 (1080p Full HD)",
                        "orientation": "landscape",
                        "duration_seconds": 10.041667,
                        "format": "MP4 (H.264)",
                        "has_audio": false,
                        "size": "3.6 MB"
                      },
                      "licence": {
                        "type": "standard",
                        "credit": null,
                        "source_url": null,
                        "url": "https://infinitylooper.com/terms#licence"
                      }
                    }
                  ],
                  "next_cursor": "eyJvIjoxfQ",
                  "total": 499
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-invalid-parameter",
                  "title": "Invalid parameter",
                  "status": 400,
                  "detail": "..."
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-rate-limited",
                  "title": "Too many requests",
                  "status": 429,
                  "detail": "..."
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          }
        }
      }
    },
    "/loops/{slug}": {
      "get": {
        "operationId": "getLoop",
        "tags": [
          "Catalogue"
        ],
        "summary": "One loop",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The loop's slug or id, for example IL-AB-0016.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The loop",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Loop"
                },
                "example": {
                  "id": "IL-AB-0016",
                  "slug": "fox-sleeping-by-a-snowy-fireplace",
                  "title": "Fox sleeping by a snowy fireplace animated background",
                  "url": "https://infinitylooper.com/free/animated-backgrounds/fox-sleeping-by-a-snowy-fireplace",
                  "description": "A fox sleeps beside a fireplace with snow-covered trees outside. A silent 10-second 1080p loop, 3.6 MB.",
                  "best_for": [
                    "TV ambience",
                    "Stream scene in OBS or Streamlabs"
                  ],
                  "tags": [
                    "fox",
                    "fireplace",
                    "snow",
                    "winter"
                  ],
                  "themes": [
                    "snow",
                    "fireplace",
                    "cute-animals"
                  ],
                  "preview_url": "https://infinitylooper.com/previews/v4/IL-AB-0016.mp4",
                  "poster_url": "https://infinitylooper.com/free/posters/hd/IL-AB-0016-640.webp",
                  "file": {
                    "width": 1916,
                    "height": 1080,
                    "resolution": "1916 x 1080 (1080p Full HD)",
                    "orientation": "landscape",
                    "duration_seconds": 10.041667,
                    "format": "MP4 (H.264)",
                    "has_audio": false,
                    "size": "3.6 MB"
                  },
                  "licence": {
                    "type": "standard",
                    "credit": null,
                    "source_url": null,
                    "url": "https://infinitylooper.com/terms#licence"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Loop not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-not-found",
                  "title": "Loop not found",
                  "status": 404,
                  "detail": "..."
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-rate-limited",
                  "title": "Too many requests",
                  "status": 429,
                  "detail": "..."
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          }
        }
      }
    },
    "/loops/{slug}/download": {
      "post": {
        "operationId": "downloadLoop",
        "tags": [
          "Downloads"
        ],
        "summary": "Get download links for a loop",
        "description": "Returns links to the full files that work for 10 minutes (expires_at). Counts as one download for the key's Google account unless the account already downloaded this loop in the rolling window, or this is a retry of the same request (same loop and Idempotency-Key). Scripts and agents may download in bulk within the account's allowance. Fetch the files straight away, from a script or server, and call again for fresh links.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The loop's slug or id, for example fox-sleeping-by-a-snowy-fireplace or IL-AB-0016.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Any unique string (1 to 128 visible ASCII characters). Retrying the same loop with the same key never counts twice; the same key on a different loop is a new download.",
            "schema": {
              "type": "string",
              "maxLength": 128
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Signed file links",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Download"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-invalid-parameter",
                  "title": "Invalid parameter",
                  "status": 400,
                  "detail": "..."
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-invalid-key",
                  "title": "Invalid API key",
                  "status": 401,
                  "detail": "This API key is not valid or has been revoked. Create a new one on your account page."
                }
              }
            }
          },
          "403": {
            "description": "Key not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-insufficient-scope",
                  "title": "Key not allowed",
                  "status": 403,
                  "detail": "..."
                }
              }
            }
          },
          "404": {
            "description": "Loop not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-not-found",
                  "title": "Loop not found",
                  "status": 404,
                  "detail": "..."
                }
              }
            }
          },
          "429": {
            "description": "The account's allowance is used up for now (type free-limit, with resets_at and a premium note), or too many requests (type rate-limited). Over 120 requests a minute from one address the edge answers 429 in plain text without Retry-After: wait a minute.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Problem"
                    },
                    {
                      "$ref": "#/components/schemas/Usage"
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-unavailable",
                  "title": "Service unavailable",
                  "status": 503,
                  "detail": "..."
                }
              }
            }
          }
        }
      }
    },
    "/themes": {
      "get": {
        "operationId": "listThemes",
        "tags": [
          "Catalogue"
        ],
        "summary": "Themes with loop counts",
        "security": [],
        "responses": {
          "200": {
            "description": "Themes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "total"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Theme"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "rain",
                      "name": "Rain",
                      "url": "https://infinitylooper.com/free/theme/rain",
                      "count": 331
                    },
                    {
                      "id": "snow",
                      "name": "Snow and winter",
                      "url": "https://infinitylooper.com/free/theme/snow",
                      "count": 289
                    }
                  ],
                  "total": 23
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-rate-limited",
                  "title": "Too many requests",
                  "status": 429,
                  "detail": "..."
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          }
        }
      }
    },
    "/me": {
      "get": {
        "operationId": "getMe",
        "tags": [
          "Downloads"
        ],
        "summary": "The key's account: plan and downloads left",
        "responses": {
          "200": {
            "description": "Usage",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Usage"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "key": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "scopes": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-invalid-key",
                  "title": "Invalid API key",
                  "status": 401,
                  "detail": "..."
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "example": {
                  "type": "https://infinitylooper.com/developers#errors-unavailable",
                  "title": "Service unavailable",
                  "status": 503,
                  "detail": "..."
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer il_live_... Create a key on your account page at https://infinitylooper.com/account."
      }
    },
    "headers": {
      "Retry-After": {
        "description": "Seconds to wait before trying again.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Policy": {
        "description": "The download allowance: \"downloads\";q=<allowance>;w=<window seconds> (IETF httpapi RateLimit draft).",
        "schema": {
          "type": "string"
        }
      },
      "RateLimit": {
        "description": "What is left: \"downloads\";r=<remaining>, plus ;t=<seconds> until a download frees up when known.",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. Switch on type.",
        "required": [
          "type",
          "title",
          "status"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "parameter": {
            "type": "string"
          },
          "premium": {
            "type": "object",
            "description": "Only on a free-limit answer: Premium Access, for people who need more downloads, is being built and cannot be bought yet.",
            "required": [
              "name",
              "status",
              "available",
              "detail"
            ],
            "properties": {
              "name": {
                "type": "string",
                "example": "Premium Access"
              },
              "status": {
                "type": "string",
                "enum": [
                  "coming_soon"
                ]
              },
              "available": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "detail": {
                "type": "string"
              }
            }
          }
        }
      },
      "Usage": {
        "type": "object",
        "required": [
          "plan",
          "limit",
          "used",
          "remaining",
          "window_days"
        ],
        "properties": {
          "plan": {
            "type": "string",
            "enum": [
              "free",
              "max"
            ]
          },
          "limit": {
            "type": "integer",
            "description": "Downloads allowed in the rolling window."
          },
          "used": {
            "type": "integer"
          },
          "remaining": {
            "type": "integer"
          },
          "resets_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the oldest counted download leaves the window. Null while there is room."
          },
          "window_days": {
            "type": "integer"
          }
        }
      },
      "File": {
        "type": "object",
        "required": [
          "name",
          "url",
          "expires_at"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "bytes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "variant": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null for the main file, else the id of a variant such as a vertical cut."
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Licence": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "credit": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          }
        }
      },
      "Loop": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "title",
          "url",
          "themes",
          "file",
          "licence"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "IL-AB-0016"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The loop's page, with a preview."
          },
          "description": {
            "type": "string"
          },
          "best_for": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "themes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "preview_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "A preview clip for showing a choice, not the full file. Get the full file with POST /loops/{slug}/download."
          },
          "poster_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "file": {
            "type": "object",
            "properties": {
              "width": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "height": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "resolution": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "orientation": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "landscape",
                  "vertical",
                  "square",
                  null
                ]
              },
              "duration_seconds": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "format": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "has_audio": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "size": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "licence": {
            "$ref": "#/components/schemas/Licence"
          }
        }
      },
      "LoopPage": {
        "type": "object",
        "required": [
          "data",
          "next_cursor",
          "total"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Loop"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "type": "integer"
          },
          "search": {
            "type": "object",
            "description": "Present when q is sent. How the words were read: the site's search treats spelling variants, synonyms and plurals as matches and sets aside a word nothing matches rather than answering empty.",
            "required": [
              "query",
              "words",
              "dropped",
              "relaxed",
              "corrected_to"
            ],
            "properties": {
              "query": {
                "type": "string"
              },
              "words": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The search words after spelling variants and stop words."
              },
              "dropped": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Words set aside because no loop matched them with the rest. All words when nothing matched."
              },
              "relaxed": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Requirements read from the words (such as vertical or 4K) that were set aside to find enough loops."
              },
              "corrected_to": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The query after typo repair, or null."
              }
            }
          }
        }
      },
      "Theme": {
        "type": "object",
        "required": [
          "id",
          "name",
          "count"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "Download": {
        "type": "object",
        "required": [
          "loop",
          "files",
          "redownload",
          "counted",
          "usage"
        ],
        "properties": {
          "loop": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "licence": {
                "$ref": "#/components/schemas/Licence"
              }
            }
          },
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/File"
            }
          },
          "redownload": {
            "type": "boolean",
            "description": "True when the account already had this loop, so nothing was counted."
          },
          "counted": {
            "type": "boolean",
            "description": "True when this call used one download."
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      }
    }
  }
}
