{
  "openapi": "3.1.0",
  "info": {
    "title": "FanEdit Catalog API",
    "version": "1.0.0",
    "description": "Authenticated metrics discovery costs zero reveal credits and excludes titles, source links, canonical IDs and creator identity. Request a specific opaque reference using id to spend one weekly credit on the full allowed record. Free: 5/week. Creator: $4.99/month, 50/week. Creator Plus: $19.99/month, 200/week. Pro: $99/month, 1000/week. Resets Monday 00:00 UTC."
  },
  "servers": [
    {
      "url": "https://www.fanedit.com"
    }
  ],
  "security": [
    {
      "catalogKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "catalogKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "fe_live_<256-bit random key>"
      }
    }
  },
  "paths": {
    "/api/v1/edits": {
      "get": {
        "operationId": "list_edits",
        "summary": "List edits",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Encrypted opaque next_cursor returned by discovery."
          },
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Opaque fe_ref_ reference returned by this resource, not a canonical platform ID."
          },
          {
            "name": "creator_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "edits",
                "all"
              ],
              "default": "edits"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Discovery page (zero credits) or specific identity reveal (one credit).",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Quota-Remaining": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Quota-Reset": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "reference": {
                                "type": "string"
                              },
                              "platform": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "views_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "likes_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "comments_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "shares_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "impact_score": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "created_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "updated_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "is_edit": {
                                "type": [
                                  "boolean",
                                  "null"
                                ]
                              },
                              "hashtags": {
                                "type": [
                                  "array",
                                  "null"
                                ],
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          },
                          {
                            "type": "object",
                            "properties": {
                              "video_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "creator_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "caption": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "platform": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "views_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "likes_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "comments_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "shares_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "impact_score": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "created_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "updated_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "is_edit": {
                                "type": [
                                  "boolean",
                                  "null"
                                ]
                              },
                              "hashtags": {
                                "type": [
                                  "array",
                                  "null"
                                ],
                                "items": {
                                  "type": "string"
                                }
                              },
                              "creator": {
                                "type": [
                                  "object",
                                  "null"
                                ],
                                "properties": {
                                  "username": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "display_name": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  }
                                }
                              }
                            },
                            "additionalProperties": false
                          }
                        ]
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "credits": {
                      "type": "integer"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid API key"
          },
          "402": {
            "description": "Inactive subscription"
          },
          "429": {
            "description": "Rate or quota limit"
          },
          "503": {
            "description": "Temporarily unavailable"
          },
          "404": {
            "description": "Specific record unavailable; no credit charged."
          }
        },
        "description": "List mode returns anonymized discovery data at zero credits. id mode returns a specific full record and consumes one reveal credit."
      }
    },
    "/api/v1/creators": {
      "get": {
        "operationId": "list_creators",
        "summary": "List creators",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Encrypted opaque next_cursor returned by discovery."
          },
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Opaque fe_ref_ reference returned by this resource, not a canonical platform ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Discovery page (zero credits) or specific identity reveal (one credit).",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Quota-Remaining": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Quota-Reset": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "reference": {
                                "type": "string"
                              },
                              "verified": {
                                "type": [
                                  "boolean",
                                  "null"
                                ]
                              },
                              "followers_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "total_play_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "likes_total": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "videos_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "total_impact_score": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              }
                            }
                          },
                          {
                            "type": "object",
                            "properties": {
                              "creator_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "username": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "display_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "bio": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "verified": {
                                "type": [
                                  "boolean",
                                  "null"
                                ]
                              },
                              "followers_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "total_play_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "likes_total": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "videos_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "total_impact_score": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              }
                            },
                            "additionalProperties": false
                          }
                        ]
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "credits": {
                      "type": "integer"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid API key"
          },
          "402": {
            "description": "Inactive subscription"
          },
          "429": {
            "description": "Rate or quota limit"
          },
          "503": {
            "description": "Temporarily unavailable"
          },
          "404": {
            "description": "Specific record unavailable; no credit charged."
          }
        },
        "description": "List mode returns anonymized discovery data at zero credits. id mode returns a specific full record and consumes one reveal credit."
      }
    },
    "/api/v1/hashtags": {
      "get": {
        "operationId": "list_hashtags",
        "summary": "List hashtags",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Encrypted opaque next_cursor returned by discovery."
          },
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Opaque fe_ref_ reference returned by this resource, not a canonical platform ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Discovery page (zero credits) or specific identity reveal (one credit).",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Quota-Remaining": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Quota-Reset": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "reference": {
                                "type": "string"
                              },
                              "hashtag": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "hashtag_norm": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "views_total": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "videos_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "creators_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "total_impact_score": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              }
                            }
                          },
                          {
                            "type": "object",
                            "properties": {
                              "hashtag": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "hashtag_norm": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "views_total": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "videos_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "creators_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "total_impact_score": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              }
                            },
                            "additionalProperties": false
                          }
                        ]
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "credits": {
                      "type": "integer"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid API key"
          },
          "402": {
            "description": "Inactive subscription"
          },
          "429": {
            "description": "Rate or quota limit"
          },
          "503": {
            "description": "Temporarily unavailable"
          },
          "404": {
            "description": "Specific record unavailable; no credit charged."
          }
        },
        "description": "List mode returns anonymized discovery data at zero credits. id mode returns a specific full record and consumes one reveal credit."
      }
    },
    "/api/v1/sounds": {
      "get": {
        "operationId": "list_sounds",
        "summary": "List sounds",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Encrypted opaque next_cursor returned by discovery."
          },
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Opaque fe_ref_ reference returned by this resource, not a canonical platform ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Discovery page (zero credits) or specific identity reveal (one credit).",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Quota-Remaining": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Quota-Reset": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "reference": {
                                "type": "string"
                              },
                              "videos_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "views_total": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "likes_total": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "total_impact_score": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              }
                            }
                          },
                          {
                            "type": "object",
                            "properties": {
                              "sound_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "sound_title": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "sound_author": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "videos_count": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "views_total": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "likes_total": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "total_impact_score": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              }
                            },
                            "additionalProperties": false
                          }
                        ]
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "credits": {
                      "type": "integer"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid API key"
          },
          "402": {
            "description": "Inactive subscription"
          },
          "429": {
            "description": "Rate or quota limit"
          },
          "503": {
            "description": "Temporarily unavailable"
          },
          "404": {
            "description": "Specific record unavailable; no credit charged."
          }
        },
        "description": "List mode returns anonymized discovery data at zero credits. id mode returns a specific full record and consumes one reveal credit."
      }
    },
    "/api/v1/communities": {
      "get": {
        "operationId": "list_communities",
        "summary": "List communities",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Encrypted opaque next_cursor returned by discovery."
          },
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Opaque fe_ref_ reference returned by this resource, not a canonical platform ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Discovery page (zero credits) or specific identity reveal (one credit).",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Quota-Remaining": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Quota-Reset": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "reference": {
                                "type": "string"
                              },
                              "linked_hashtags": {
                                "type": [
                                  "array",
                                  "null"
                                ],
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          },
                          {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "slug": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "description": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "linked_hashtags": {
                                "type": [
                                  "array",
                                  "null"
                                ],
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "additionalProperties": false
                          }
                        ]
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "credits": {
                      "type": "integer"
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid API key"
          },
          "402": {
            "description": "Inactive subscription"
          },
          "429": {
            "description": "Rate or quota limit"
          },
          "503": {
            "description": "Temporarily unavailable"
          },
          "404": {
            "description": "Specific record unavailable; no credit charged."
          }
        },
        "description": "List mode returns anonymized discovery data at zero credits. id mode returns a specific full record and consumes one reveal credit."
      }
    }
  }
}
