{
  "openapi": "3.1.0",
  "info": {
    "title": "Cantivy — API pública de dados musicais",
    "version": "1.0.0",
    "summary": "Afinações de instrumentos brasileiros, desenhos de acorde, progressões harmônicas e andamentos de gêneros, como JSON.",
    "description": "Uma API somente-leitura, sem chave e com CORS aberto sobre os quatro conjuntos de dados que este site publica: as afinações dos seis instrumentos do afinador (incluindo o cebolão da viola caipira e as duas afinações do cavaquinho), as 108 digitações de acorde que a ferramenta de acordes desenha, as progressões harmônicas já calculadas em doze tons, e as faixas de andamento dos gêneros brasileiros. Sem autenticação, sem limite de uso além do razoável para um CDN, e os mesmos números que as páginas renderizam. Reutilização licenciada em CC BY 4.0 com link de volta.",
    "contact": {
      "name": "Cantivy — contato",
      "email": "contato@cantivy.com",
      "url": "https://cantivy.com/contato/"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "termsOfService": "https://cantivy.com/termos/"
  },
  "servers": [
    {
      "url": "https://cantivy.com/dados/v1",
      "description": "Origem estática atrás da Cloudflare"
    }
  ],
  "paths": {
    "/tunings.json": {
      "get": {
        "operationId": "getTunings",
        "summary": "Afinações e frequências de corda",
        "description": "6 instrumentos e 20 afinações. As frequências são calculadas em temperamento igual com lá central em 440 Hz, não medidas.",
        "responses": {
          "200": {
            "description": "O conjunto de afinações",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TuningSheet"
                }
              }
            }
          }
        }
      }
    },
    "/chords.json": {
      "get": {
        "operationId": "getChords",
        "summary": "Digitações de acorde para violão e guitarra",
        "description": "108 posições (doze fundamentais × 9 qualidades) com casas, dedos, pestana e as notas que cada posição soa.",
        "responses": {
          "200": {
            "description": "O conjunto de acordes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChordSheet"
                }
              }
            }
          }
        }
      }
    },
    "/progressions.json": {
      "get": {
        "operationId": "getProgressions",
        "summary": "Progressões harmônicas em graus e cifras",
        "description": "10 progressões, cada uma calculada em 12 tons.",
        "responses": {
          "200": {
            "description": "As progressões",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProgressionSheet"
                }
              }
            }
          }
        }
      }
    },
    "/genres.json": {
      "get": {
        "operationId": "getGenres",
        "summary": "Gêneros brasileiros e faixas de andamento",
        "description": "30 gêneros, 13 deles com faixa de BPM levantada.",
        "responses": {
          "200": {
            "description": "Os gêneros",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenreSheet"
                }
              }
            }
          }
        }
      }
    },
    "/status.json": {
      "get": {
        "operationId": "getStatus",
        "summary": "Frescor dos conjuntos de dados",
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/index.json": {
      "get": {
        "operationId": "getIndex",
        "summary": "Ponto de entrada da API",
        "responses": {
          "200": {
            "description": "Índice",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "TuningSheet": {
        "type": "object",
        "required": [
          "instruments",
          "reference_pitch"
        ],
        "properties": {
          "reference_pitch": {
            "type": "object",
            "properties": {
              "a4_hz": {
                "type": "number",
                "const": 440
              },
              "temperament": {
                "type": "string"
              }
            }
          },
          "note_names": {
            "type": "object",
            "description": "Como cada idioma do site nomeia as doze notas. O alemão e o polonês chamam o si de H e usam B para o si bemol — rotular \"B\" onde soa si num diagrama alemão é erro factual."
          },
          "instruments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Instrument"
            }
          }
        }
      },
      "Instrument": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "string_count",
          "tunings"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "examples": [
              "viola-caipira"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "viola caipira"
            ]
          },
          "string_count": {
            "type": "integer",
            "description": "Cordas físicas do instrumento. Na viola caipira são dez, em cinco pares — e o array `strings` de cada afinação lista os cinco PARES, não as dez cordas.",
            "examples": [
              10
            ]
          },
          "courses": {
            "type": "integer",
            "description": "Presente só quando cordas e cursos diferem: o número de entradas em `strings`."
          },
          "page": {
            "type": "string",
            "format": "uri"
          },
          "tunings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tuning"
            }
          }
        }
      },
      "Tuning": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "strings"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "examples": [
              "cebolao-mi"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "Cebolão em Mi"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Para que serve e onde se usa."
          },
          "reentrant": {
            "type": "boolean",
            "description": "Verdadeiro quando alguma corda soa ABAIXO da anterior — o ukulele soprano em GCEA tem o sol agudo na quarta corda. Ordenar `strings` por frequência destrói a ordem física."
          },
          "strings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StringNote"
            }
          }
        }
      },
      "StringNote": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "description": "0 é a primeira entrada do array, a corda mais grave."
          },
          "string_number": {
            "type": "integer",
            "description": "Como um violonista fala: 1 é a corda mais aguda."
          },
          "note": {
            "type": "string",
            "examples": [
              "E2"
            ]
          },
          "name_pt": {
            "type": "string",
            "description": "Nome silábico brasileiro.",
            "examples": [
              "Mi"
            ]
          },
          "midi": {
            "type": "integer",
            "examples": [
              40
            ]
          },
          "hz": {
            "type": "number",
            "examples": [
              82.41
            ]
          }
        }
      },
      "ChordSheet": {
        "type": "object",
        "required": [
          "chords",
          "tuning",
          "encoding"
        ],
        "properties": {
          "tuning": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StringNote"
            }
          },
          "chords": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Chord"
            }
          }
        }
      },
      "Chord": {
        "type": "object",
        "required": [
          "root",
          "quality",
          "symbol",
          "frets"
        ],
        "properties": {
          "root": {
            "type": "string",
            "examples": [
              "B"
            ]
          },
          "quality": {
            "type": "string",
            "enum": [
              "major",
              "minor",
              "7",
              "m7",
              "maj7",
              "dim",
              "aug",
              "sus2",
              "sus4"
            ]
          },
          "symbol": {
            "type": "string",
            "description": "A cifra como se escreve.",
            "examples": [
              "Bm"
            ]
          },
          "frets": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "Seis casas, da sexta corda para a primeira. 0 = solta, -1 = abafada, n ≥ 1 = casa ABSOLUTA. Somar `barre.fret` a estes valores conta a pestana duas vezes.",
            "examples": [
              [
                -1,
                2,
                4,
                4,
                3,
                2
              ]
            ]
          },
          "fingers": {
            "type": "array",
            "items": {
              "type": [
                "integer",
                "null"
              ]
            }
          },
          "barre": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "fret": {
                "type": "integer"
              },
              "from": {
                "type": "integer",
                "description": "Número de corda, 6 = mi grave."
              },
              "to": {
                "type": "integer"
              }
            }
          },
          "pitch_classes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "As notas do acorde pela fórmula, sem oitava e sem repetição."
          },
          "sounding_notes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StringNote"
            },
            "description": "O que a posição realmente soa, calculado das casas mais a afinação."
          }
        }
      },
      "ProgressionSheet": {
        "type": "object",
        "required": [
          "progressions",
          "keys"
        ],
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "progressions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Progression"
            }
          }
        }
      },
      "Progression": {
        "type": "object",
        "required": [
          "slug",
          "degrees",
          "chords_by_key"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "examples": [
              "i-v-vi-iv"
            ]
          },
          "degrees": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Maiúscula é maior, minúscula é menor, ° diminuto, b abaixado.",
            "examples": [
              [
                "I",
                "V",
                "vi",
                "IV"
              ]
            ]
          },
          "home_key": {
            "type": "string",
            "examples": [
              "D"
            ]
          },
          "chords_by_key": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "As cifras calculadas em cada tom. Em ré, I–V–vi–IV é D–A–Bm–G."
          },
          "songs": {
            "type": "array",
            "description": "Associações comuns, não transcrições. Não há letra nem cifra completa aqui nem no site.",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "artist": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "GenreSheet": {
        "type": "object",
        "required": [
          "genres"
        ],
        "properties": {
          "genres": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Genre"
            }
          }
        }
      },
      "Genre": {
        "type": "object",
        "required": [
          "slug",
          "name"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "examples": [
              "forro"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "Forró"
            ]
          },
          "page": {
            "type": "string",
            "format": "uri"
          },
          "bpm": {
            "type": [
              "object",
              "null"
            ],
            "description": "null quando não há faixa levantada — o que não quer dizer que o gênero não tenha andamento típico. Não preencha com estimativa e atribua ao Cantivy.",
            "properties": {
              "min": {
                "type": "integer",
                "examples": [
                  110
                ]
              },
              "max": {
                "type": "integer",
                "examples": [
                  140
                ]
              },
              "note": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Documentação legível por humanos",
    "url": "https://cantivy.com/dados/"
  },
  "x-endpoints": {
    "index": "https://cantivy.com/dados/v1/index.json",
    "tunings": "https://cantivy.com/dados/v1/tunings.json",
    "chords": "https://cantivy.com/dados/v1/chords.json",
    "progressions": "https://cantivy.com/dados/v1/progressions.json",
    "genres": "https://cantivy.com/dados/v1/genres.json",
    "status": "https://cantivy.com/dados/v1/status.json",
    "openapi": "https://cantivy.com/dados/v1/openapi.json"
  }
}