Criar e importar estudos

Esta página cobre o ciclo de vida do estudo pela API: criar, importar, consultar, renomear, excluir e comparar versões. Autenticação, Operation, Idempotency-Key e erros comuns estão na visão geral.

Há três formas de começar um estudo:

Objetivo	Rota	Resultado
Estudo pronto, com as rodadas padrão da organização	POST /studies/fast-track	Rodadas criadas e decks montados.
Estudo a partir de decks que você já tem	POST /studies/imports	Rodadas criadas a partir do ZIP.
Só o cadastro, para expandir depois	POST /studies	Estudo sem rodadas.

As três respondem 202 Operation. Acompanhe o pedido e leia result.study_key quando ele terminar. Para fazer o mesmo pelo Portal, veja Criar um estudo e Importar um estudo.

Fast Track

POST /studies/fast-track cria o estudo operacional com as rodadas padrão da organização. O servidor escolhe PMO, revisão (RV), cortes, PREVS e DECOMP base a partir da configuração da organização; esses valores não são parâmetros da API. Se a organização ainda não tiver PREVS publicado, o estudo é criado, mas fica not_ready até a fonte existir. O Myria nunca usa o PREVS de outra organização.

O corpo é opcional:

curl -sS -X POST "$MYRIA_API/api/v1/studies/fast-track" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fast-track-2026-09-001" \
  -d '{"name":"Cenário hidrológico","description":"Rodada semanal"}'

Campo	Uso
name	Título do estudo. Sem ele, o Myria gera um título automático com o modelo, o mês, as revisões (RV) e a data de criação, que acompanha as rodadas DECOMP criadas depois.
description	Texto livre, até 10.000 caracteres.
deck_rules_profile	Perfil de regras de deck usado na criação. Sem ele, vale o perfil padrão atual da organização.

deck_rules_profile aceita dois modos:

• {"mode": "organization_default"}: usa o perfil da organização. Com expected_revision, o pedido é recusado com 409 (deck_rules_organization_profile_revision_conflict) se o perfil tiver mudado desde a sua leitura.
• {"mode": "explicit", "ordered_source_items": [...]}: define a sequência de regras só para este estudo; aceita também model_defaults e phase_policy. Cards precisam estar resolvidos antes, na forma {tipo:"upload",id,sha256}. Veja Regras de deck.

O pedido só chega a succeeded depois que os decks foram montados e a prontidão do estudo foi calculada. Em result, a API devolve:

{
  "study_key": "minha-org-191",
  "number": "191",
  "title": "Cenário hidrológico",
  "pmo": "202609",
  "rv": 2,
  "rounds": [
    {"round_key": "minha-org-205", "number": "205", "name": "NW 09/26", "type": "newave"},
    {"round_key": "minha-org-206", "number": "206", "name": "DC 09/26 RV2", "type": "decomp"}
  ],
  "materialization": {"mode": "generic_study", "status": "completed"},
  "study": {"study_key": "minha-org-191", "readiness": "ready"}
}

study traz o estudo completo, como em GET /studies/{study_key}; o exemplo mostra só dois campos. Se a montagem dos decks falhar, o pedido termina em failed com materialization_failed e result.materialization.status: "failed". Se a configuração gerada for inválida, o pedido termina em failed e nenhum estudo é criado.

Se a montagem dos decks ficar trinta minutos sem progresso, o pedido passa para attention_required com reason_code: "study_materialization_stale". Consultar o pedido não reinicia esse prazo. Se a montagem terminar depois, o pedido ainda chega a succeeded ou failed. Não crie outro estudo para substituir uma montagem pendente; fale com a equipe Myria.

As rodadas recebem nomes legíveis: NW 09/26 para NEWAVE e DC 09/26 RV2 para DECOMP. Uma segunda rodada com o mesmo mês e RV recebe um ordinal, como DC 09/26 RV2 · 2.

Importar um ZIP

POST /studies/imports recebe multipart/form-data com o arquivo em file e, opcionalmente, o título em name. Qualquer outro campo é recusado com 400 invalid_payload. O limite é 128 MiB.

curl -sS -X POST "$MYRIA_API/api/v1/studies/imports" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Idempotency-Key: importar-2026-09-001" \
  -F "file=@./estudo.zip" \
  -F "name=Estudo importado"

O que o ZIP precisa ter:

• ao menos um deck de entrada identificável por dger.* (NEWAVE) ou dadger.* (DECOMP); um ZIP só com saídas não cria estudo;
• no máximo um NEWAVE por PMO. Um ZIP pode ter vários meses; os decks são ordenados pelo PMO e pela revisão (RV) do DECOMP. Dois NEWAVE do mesmo PMO fazem a importação ser recusada;
• nenhuma pasta deck_rules/ nem earm_control_report.json: esses arquivos são gerados pelo Myria.

A importação preserva o conteúdo dos arquivos e só normaliza os nomes. Ela não busca fontes externas nem altera ARQUIVOS.DAT. Alguns ajustes são feitos automaticamente:

• um DECOMP sem caso.dat, mas com um único dadger.rvN e o arquivo rvN correspondente, recebe um caso.dat apontando para essa revisão;
• em uma sequência de vários meses no mesmo ZIP, ADTERM e VAZPAST do NEWAVE e DADGNL do DECOMP ausentes são completados a partir do mês anterior do próprio ZIP. Outros insumos ausentes aparecem no diagnóstico da rodada;
• um DECOMP importado usa o bloco UH do próprio deck como origem da EARM base, até que você escolha outra fonte nas opções da rodada.

Um DECOMP importado sem arquivos de cortes é importado, mas não executa até que você configure os cortes (decomp_cuts) com uma fonte NEWAVE. Veja Configurar rodadas. Se o ZIP trouxer o NEWAVE do mesmo mês, ele pode fornecer os cortes.

Em succeeded, result traz study_key, number, deck_version e warnings. Se algum deck não puder ser montado, o pedido falha com um código zip_v4_* e nenhuma rodada fica disponível para execução.

A importação recusa ZIPs com taxa de compressão suspeita, tanto no total quanto em cada arquivo, para proteger o servidor.

Criar só o cadastro

POST /studies aceita name e description e cria um estudo sem rodadas. Não aceita YAML bruto nem modelos prontos.

curl -sS -X POST "$MYRIA_API/api/v1/studies" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cadastro-2026-09-001" \
  -d '{"name":"Estudo vazio","description":"Rodadas serão criadas depois"}'

Se a organização tiver um perfil padrão de regras, o estudo guarda uma cópia dele na criação; mudanças posteriores no perfil da organização não alteram o estudo. Para criar as primeiras rodadas, use incremental-operations a partir de uma base externa.

Consultar e renomear

GET /studies lista os estudos da organização (paginação por cursor). GET /studies/{study_key} devolve o estudo:

{
  "study_key": "minha-org-191",
  "name": "Cenário hidrológico",
  "description": null,
  "deck_version": "0123456789abcdef0123456789abcdef01234567",
  "readiness": "ready",
  "availability": "available",
  "deleted": false,
  "rodadas": [
    {"round_key": "minha-org-206", "nome": "DC 09/26 RV2", "tipo": "decomp",
     "rv": "rv2", "ordem": 2, "status": "pending", "readiness": "ready", "is_valid": true}
  ]
}

readiness vale ready, not_ready, attention_required, blocked ou unknown. Execute só estudos em ready. deck_version é a versão atual da configuração; várias rotas de alteração pedem esse valor como base_deck_version para evitar que um pedido sobrescreva outro.

Cada rodada traz também errors e avisos_cards:

• errors lista o que impede a rodada: falhas da montagem do deck, checagens de execução pendentes (code: "readiness_blocked") e, quando a execução falhou antes de o modelo começar, um item code: "execution_attempt_failed" com reason_code e message. Falhas internas de aplicação citam o Card, a entrada e o código; incompatibilidades cadastrais/temporais são avisos. Detalhes internos nunca aparecem; uma falha interna vem com uma referência curta (codigo de suporte ...) para informar ao suporte.
• avisos_cards lista as decisões de compatibilidade da última montagem, cada uma com codigo, titulo, caminho, mensagem e desfecho. O desfecho pode ser ignorada, adaptada, parcial, aplicada ou sobrescrita. Por exemplo, restriction_identifier_reconciled informa os números de restrição do deck e da Base comprovados pela mesma composição. Cadastro ausente preserva os valores e gera ignorada; período parcialmente coberto gera parcial. A rodada continua válida. Aplicações ordinárias aparecem no diff/recibo; a lista é refeita a cada nova montagem e a retirada do Card limpa seus avisos. Erros da Base, das fontes e de integridade seguem em errors.

PATCH /studies/{study_key} altera só name e description. É síncrono: responde 200 com o estudo, sem Operation. Exige Idempotency-Key e aceita If-Match com a deck_version atual; se a versão tiver mudado, a resposta é 409 (base_deck_version_conflict). Um name explícito desliga o título automático.

curl -sS -X PATCH "$MYRIA_API/api/v1/studies/$STUDY_KEY" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: renomear-191-001" \
  -d '{"name":"Cenário seco"}'

Excluir

DELETE /studies/{study_key} não tem corpo e responde 202 Operation. O estudo sai das listagens na hora e deixa de aceitar alterações e execuções. O pedido então cancela pedidos ainda na fila, para a execução ativa, se houver, e remove os arquivos. Enquanto uma execução ou uma retenção impedir a remoção, o pedido continua em andamento. Se o Myria não conseguir confirmar que a limpeza é segura, o pedido vai para attention_required e nada é apagado.

Repetir a mesma Idempotency-Key devolve o mesmo pedido. Depois que o estudo foi marcado como excluído, uma chave nova não inicia outra exclusão.

Se o estudo estiver em execução, a exclusão primeiro espera a confirmação de que a execução parou. Depois que o estudo é marcado como excluído, nenhum resultado novo é publicado. Os registros dos resultados anteriores continuam disponíveis para auditoria; os arquivos só são apagados depois da parada confirmada e do fim do prazo de retenção.

A remoção de uma rodada parada aguarda a parada terminar. Enquanto isso, a remoção responde 409 sem alterar o estudo.

Versões

Cada alteração de configuração cria uma versão, identificada por sha. GET /studies/{study_key}/versions lista as versões (mais recentes primeiro) e GET /studies/{study_key}/versions/{sha} devolve uma delas, com schema_version, classification, origin, availability, yaml_hash e created_at.

availability vale available, expired, missing ou quarantined (isolada depois de falhar numa verificação de integridade). Onde não há nada configurado, aparece unset.

Comparar e validar versões

A versão de referência (baseline) é o ponto de partida das comparações.

• GET /studies/{study_key}/baseline devolve sha, availability e set_at (sha: null e availability: "unset" quando não há referência).
• PUT /studies/{study_key}/baseline recebe {"sha": "..."} de uma versão do estudo e responde 200.
• POST /studies/{study_key}/diffs recebe from_sha e to_sha, ambos opcionais: sem eles, compara a versão de referência com a versão atual. Sem from_sha e sem versão de referência, a resposta é 409 (baseline_not_set).
• POST /studies/{study_key}/validations recebe {"sha": "..."}.

Diffs e validações respondem 202 Operation; o resultado vem em result quando o pedido termina.

curl -sS -X POST "$MYRIA_API/api/v1/studies/$STUDY_KEY/diffs" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: diff-191-001" \
  -d '{}'