API para usuários: visão geral

A API permite que os sistemas da sua equipe criem ou importem estudos, configurem rodadas, executem os modelos e baixem os resultados sem passar pelo navegador. Esta página reúne o que vale para todas as chamadas: autenticação, identificadores, acompanhamento de pedidos, idempotência, paginação, erros e limites. Cada grupo de rotas tem uma página própria, listada na tabela de endpoints.

A URL base é /api/v1. As respostas usam JSON, exceto os downloads. Os exemplos usam MYRIA_API para o endereço do seu ambiente e MYRIA_TOKEN para a chave de acesso. Substitua o endereço abaixo pelo fornecido à sua organização e mantenha a chave fora de arquivos compartilhados:

export MYRIA_API="https://seu-ambiente-myria.example"
export MYRIA_TOKEN="myria_live_..."

Para consultar os campos de cada rota e testar chamadas no navegador, use a referência interativa Scalar, gerada a partir da especificação OpenAPI. As páginas desta seção explicam os fluxos; a referência interativa descreve cada campo.

cuidado

A referência interativa envia requisições reais ao ambiente aberto no navegador. Criar, alterar, executar ou excluir recursos tem efeito nesse ambiente. Informe a chave em bearerAuth; ela é esquecida ao recarregar a página.

Criar uma chave de acesso

No Portal, abra Perfil e, em Chaves de API, clique em Minhas chaves. Em Nova chave, dê um nome, escolha as permissões e clique em Criar chave. O segredo aparece uma única vez, em Segredo criado: copie-o nesse momento. Sem uma data de expiração, a chave vale por 90 dias. Uma chave que não será mais usada pode ser encerrada em Revogar. Administradores da organização veem todas as chaves em Chaves da organização. O passo a passo está em Perfil.

Envie a chave em todas as requisições:

Authorization: Bearer myria_live_<public_id>.<secret>

Permissões

Cada chave tem um conjunto de permissões (scopes):

Permissão	Autoriza
studies:read	Consultar estudos, versões, entradas, topologia, configuração e regras; gerar prévias.
studies:write	Criar, importar, alterar e excluir estudos, rodadas, regras e entradas.
executions:read	Consultar execuções e baixar seus resultados.
executions:write	Iniciar e parar execuções.
webhooks:read	Consultar a configuração e as entregas de webhook.
webhooks:write	Configurar ou desligar o webhook, trocar o segredo e refazer entregas.

As rotas de /operations aceitam a permissão de leitura (ou de escrita, para cancelar) do domínio do pedido: uma chave só com studies:read não enxerga pedidos de execução, por exemplo.

Um recurso inexistente e um recurso de outra organização respondem com o mesmo 404.

Identidade de estudos e rodadas

A API identifica estudos por study_key e rodadas por round_key. As duas chaves têm o formato <slug-da-organização>-<número>, por exemplo minha-org-42. Elas não mudam quando o estudo ou a rodada é renomeado. Nomes exibidos não servem como identificadores.

As rotas de rodada ficam sob o estudo: /studies/{study_key}/rodadas/{round_key}/.... A API confere que a rodada pertence ao estudo informado e à organização da chave; caso contrário, responde 404.

Os demais identificadores públicos têm prefixos estáveis, como op_<32 hex> (pedidos), exec_... (execuções), leg_... (etapas), attempt_... (tentativas), inp_... (entradas), manifest_... e art_... (resultados), rules_... (regras enviadas), catalog_... (Cards do catálogo) e source-... (fontes externas). delivery_id e event_id de webhooks são UUIDs. Trate todos como texto opaco.

Vocabulário

Alguns nomes aparecem em inglês porque fazem parte das URLs e do JSON:

Nome na API	O que significa
Study (estudo)	Configuração, arquivos de entrada e histórico de execuções de um cenário.
Version (versão)	Uma versão imutável da configuração do estudo, identificada pelo campo sha. O estudo expõe a versão atual em deck_version.
Input (arquivo de entrada)	Um arquivo usado por uma rodada, como um PREVS, ou um ZIP parcial com várias entradas.
Operation (acompanhamento)	O protocolo de um trabalho que continua depois da resposta HTTP.
Execution (execução)	Um pedido para rodar o estudo inteiro ou parte das rodadas.
Leg (etapa da execução)	A execução de uma rodada dentro de uma execução.
Attempt (tentativa)	Uma tentativa de processar uma etapa.
Artifact (arquivo de resultado)	Um arquivo produzido pela execução, como log, relatório ou deckoutput.json.
Manifest (conjunto de resultados)	A lista fechada dos arquivos coletados em uma tentativa.
Baseline (versão de referência)	A versão escolhida como ponto de partida para comparações.

Acompanhar pedidos (Operation)

Importações, criações, alterações de deck, execuções e exclusões continuam depois da resposta HTTP. Essas rotas respondem 202 Accepted com os dados para acompanhar o pedido:

{
  "operation_id": "op_0123456789abcdef0123456789abcdef",
  "status": "queued",
  "status_url": "/api/v1/operations/op_0123456789abcdef0123456789abcdef"
}

Consulte status_url até terminal ser true:

status	Significado
queued	O pedido foi aceito e aguarda processamento.
running	O Myria está processando o pedido.
attention_required	O pedido precisa de análise. Leia reason_code e action_required. Esse estado não confirma que um processamento remoto foi interrompido.
succeeded	Terminou com sucesso. Os identificadores criados estão em result.
failed	Falhou. Leia error e reason_code.
cancelled	Foi cancelado antes de terminar.

A resposta também traz kind e domain (o tipo de pedido), progress, revision, created_at, started_at e finished_at. GET /operations lista os pedidos visíveis para a chave, com paginação por cursor.

cancellable informa se o pedido ainda aceita cancelamento. Para cancelar, use POST /operations/{operation_id}/cancel com Idempotency-Key; a resposta é 200 com a Operation atualizada. Um pedido que já passou do ponto sem volta responde 409 com operation_not_cancellable.

Quando um pedido concluído se refere a um estudo que foi excluído depois, GET /operations/{operation_id} responde 410 com operation_resource_gone. Na listagem, esse pedido aparece com resource_gone: true e result vazio.

Evitar pedidos duplicados (Idempotency-Key)

Toda chamada que cria, altera, executa, cancela ou exclui algo exige o cabeçalho Idempotency-Key, inclusive POST /operations/{operation_id}/cancel:

Idempotency-Key: importar-estudo-agosto-001

A chave tem de 1 a 255 caracteres, sem caracteres de controle; espaços nas pontas são descartados. Gere um valor único para cada pedido do seu sistema e guarde-o com o pedido. Se houver timeout ou perda de conexão, repita a mesma requisição com a mesma chave: o Myria devolve o resultado original sem fazer o trabalho de novo.

Reutilizar a chave com outro corpo, rota ou recurso retorna 409 com idempotency_key_reused. Para tentar de novo um pedido que falhou, envie uma chave nova.

Não usam Idempotency-Key as chamadas que apenas calculam e não gravam nada: POST /deck-rules/validate, POST .../incremental-operations/preview, POST .../configuration/preview e POST .../earm-preview. A prévia do deck montado (POST .../deck-rules/preview) exige a chave, porque cria um pedido acompanhado por Operation.

Paginação

As listagens aceitam limit de 1 a 100 (padrão 50). Quando houver outra página, copie next_cursor para o parâmetro cursor da chamada seguinte:

{"data": [], "page": {"limit": 50, "next_cursor": null, "has_more": false}}

curl -sS "$MYRIA_API/api/v1/studies?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $MYRIA_TOKEN"

Envie o cursor exatamente como recebeu. A API usa cursor, nunca offset; o parâmetro offset é recusado com offset_not_supported.

A exceção é GET /studies/{study_key}/rodadas/{round_key}/files: essa rota aceita só limit e devolve page.limit e page.has_more, sem cursor.

Erros

Todo erro usa a mesma estrutura:

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "Idempotency-Key ja foi usada com outra requisicao.",
    "details": {}
  },
  "request_id": "req_4f0c2b9e8d7a4c1b9e3f5a6d7c8b9a0e"
}

request_id tem o formato req_<32 hex> e também vem no cabeçalho X-Request-ID. Informe esse valor ao abrir um chamado. Use error.code na sua integração; message é um texto para pessoas e pode mudar.

HTTP	Quando acontece	Códigos frequentes
400	Campo ausente, valor inválido, campo desconhecido ou combinação não permitida.	invalid_payload, invalid_json, missing_idempotency_key, invalid_idempotency_key, invalid_limit, offset_not_supported
401	Chave ausente, malformada, desconhecida, revogada ou expirada. A resposta traz WWW-Authenticate: Bearer.	missing_api_key, invalid_api_key, revoked_api_key, expired_api_key
403	A chave não tem a permissão exigida, ou a fonte Git escolhida está fora das pastas autorizadas.	insufficient_scope, forbidden_prevs_source
404	Recurso inexistente ou de outra organização.	not_found
405	Método HTTP não aceito pela rota. O cabeçalho Allow lista os métodos válidos.	method_not_allowed
409	Versão ou número de revisão desatualizado, chave de idempotência reutilizada, estudo ocupado por outro pedido, pedido que não pode mais ser cancelado.	idempotency_key_reused, operation_not_cancellable, study_execution_active
410	O prazo de retenção do arquivo terminou, ou o estudo de um pedido concluído foi excluído.	artifact_expired, operation_resource_gone
413	Arquivo acima do limite.	file_too_large, deck_rules_source_too_large
415	Content-Type diferente do esperado (JSON ou multipart/form-data).	unsupported_media_type
422	O conteúdo é bem formado, mas não pode ser aplicado: regras, perfil ou configuração inválidos.	varia por rota
429	Limite de requisições atingido.	rate_limited
500	Erro interno. Guarde o request_id.	internal_error
502	O serviço de cálculo de EARM não respondeu à prévia.	earm_upstream_unavailable
503	Armazenamento ou fonte Git temporariamente indisponível. Tente de novo mais tarde.	artifact_storage_unavailable, prevs_source_head_unavailable

Os códigos específicos de cada rota aparecem nas páginas de cada grupo.

Limites de requisições

As chamadas que criam ou alteram algo consomem uma cota por hora. A cota vale para cada chave e, com valor dez vezes maior, para a organização inteira. A contagem recomeça a cada hora cheia do relógio. Os limites padrão são:

Grupo	Rotas	Por chave	Por organização
Estudos	POST /studies, POST /studies/fast-track	30/hora	300/hora
Envios	POST /studies/imports, POST e DELETE em /inputs	30/hora	300/hora
Execuções	POST /studies/{study_key}/executions	60/hora	600/hora
Expansões	POST .../incremental-operations e .../incremental-operations/preview	60/hora	600/hora
Configurações	opções, configuração da rodada (alteração, prévia e aplicação), sensibilidades, diffs, validações, prévia do deck e resolução de Cards	60/hora	600/hora
Prévias de EARM	POST .../earm-preview	30/hora	300/hora
Paradas	POST /executions/{execution_id}/stop	60/hora	600/hora
Exclusões	DELETE /studies/{study_key}	30/hora	300/hora
Webhook	PUT e DELETE /webhook, POST /webhook/rotate-secret, cada um	30/hora	300/hora
Reenvios de webhook	POST .../redeliver	60/hora	600/hora

Repetir a mesma Idempotency-Key de um pedido já aceito não consome cota. Prévias que não usam Idempotency-Key consomem cota a cada chamada. Leituras não consomem essas cotas.

Falhas de autenticação também são limitadas: 60 por minuto por endereço IP e 10 por minuto por chave. Acima disso, a API responde 429 mesmo que a chave seguinte esteja correta.

Ao atingir um limite, a resposta é 429 com rate_limited, o cabeçalho Retry-After (segundos até liberar) e X-RateLimit-Limit. Em details, a API informa action, bucket (key ou org), limit, window_seconds e retry_after_seconds. Aguarde o tempo indicado antes de repetir.

Exemplo completo: criar e executar

Este exemplo cria um estudo com as rodadas padrão da organização (Fast Track), executa e baixa um resultado.

1. Crie o estudo:

   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-agosto-001" \
     -d '{"name":"Cenário hidrológico de agosto","description":"Criado pela API"}'

2. Acompanhe o pedido até terminal: true:

   curl -sS "$MYRIA_API/api/v1/operations/$OPERATION_ID" \
     -H "Authorization: Bearer $MYRIA_TOKEN"

   Em succeeded, os decks já foram montados. Pegue result.study_key.

3. Confirme que o estudo está pronto (readiness: "ready"):

   curl -sS "$MYRIA_API/api/v1/studies/$STUDY_KEY" \
     -H "Authorization: Bearer $MYRIA_TOKEN"

4. Inicie a execução de todas as rodadas:

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

5. Acompanhe a nova Operation. Em succeeded, pegue result.execution_id e acompanhe a execução até status sair de running:

   curl -sS "$MYRIA_API/api/v1/executions/$EXECUTION_ID" \
     -H "Authorization: Bearer $MYRIA_TOKEN"

6. Liste os resultados mais recentes e baixe um deles pelo artifact_id:

   curl -sS "$MYRIA_API/api/v1/executions/$EXECUTION_ID/artifacts" \
     -H "Authorization: Bearer $MYRIA_TOKEN"
   
   curl -sS -f -o resultado.bin \
     "$MYRIA_API/api/v1/executions/$EXECUTION_ID/artifacts/$ARTIFACT_ID/download" \
     -H "Authorization: Bearer $MYRIA_TOKEN"

Para receber avisos em vez de consultar a API em intervalos, configure um webhook.

Todos os endpoints

As rotas são relativas a /api/v1. A coluna "Página" leva à explicação do fluxo; os campos estão na referência interativa.

Tarefa	Método e rota	Permissão	Resposta	Página
Listar estudos	GET /studies	studies:read	200, lista	Estudos
Criar só o cadastro	POST /studies	studies:write	202 Operation	Estudos
Criar com Fast Track	POST /studies/fast-track	studies:write	202 Operation	Estudos
Importar ZIP	POST /studies/imports	studies:write	202 Operation	Estudos
Consultar estudo	GET /studies/{study_key}	studies:read	200 Study	Estudos
Alterar nome ou descrição	PATCH /studies/{study_key}	studies:write	200 Study	Estudos
Excluir estudo	DELETE /studies/{study_key}	studies:write	202 Operation	Estudos
Listar versões	GET /studies/{study_key}/versions	studies:read	200, lista	Estudos
Consultar versão	GET /studies/{study_key}/versions/{sha}	studies:read	200 Version	Estudos
Consultar versão de referência	GET /studies/{study_key}/baseline	studies:read	200 Baseline	Estudos
Definir versão de referência	PUT /studies/{study_key}/baseline	studies:write	200 Baseline	Estudos
Comparar versões	POST /studies/{study_key}/diffs	studies:write	202 Operation	Estudos
Validar versão	POST /studies/{study_key}/validations	studies:write	202 Operation	Estudos
Consultar topologia	GET /studies/{study_key}/topology	studies:read	200	Expandir
Pré-visualizar RV+, M+ ou D+	POST /studies/{study_key}/incremental-operations/preview	studies:read	200	Expandir
Criar RV+, M+ ou D+	POST /studies/{study_key}/incremental-operations	studies:write	202 Operation	Expandir
Listar sensibilidades	GET /studies/{study_key}/rodadas/{round_key}/sensitivities	studies:read	200, lista	Expandir
Criar sensibilidades	POST /studies/{study_key}/rodadas/{round_key}/sensitivities	studies:write	202 Operation	Expandir
Consultar opções da rodada	GET /studies/{study_key}/rodadas/{round_key}/options	studies:read	200	Configurar
Alterar opções da rodada	PATCH /studies/{study_key}/rodadas/{round_key}/options	studies:write	202 Operation	Configurar
Listar executáveis	GET /binaries	studies:read	200	Configurar
Consultar configuração	GET /studies/{study_key}/rodadas/{round_key}/configuration	studies:read	200	Configurar
Salvar configuração	PATCH /studies/{study_key}/rodadas/{round_key}/configuration	studies:write	200	Configurar
Pré-visualizar configuração	POST /studies/{study_key}/rodadas/{round_key}/configuration/preview	studies:read	200	Configurar
Aplicar configuração	POST /studies/{study_key}/rodadas/{round_key}/configuration/apply	studies:write	202 Operation	Configurar
Simular ajuste de EARM	POST /studies/{study_key}/rodadas/{round_key}/earm-preview	studies:read	200	Configurar
Listar entradas	GET /studies/{study_key}/inputs	studies:read	200, lista	Configurar
Enviar entrada	POST /studies/{study_key}/inputs	studies:write	202 Operation	Configurar
Excluir entrada	DELETE /studies/{study_key}/inputs/{input_id}	studies:write	202 Operation	Configurar
Listar arquivos da rodada	GET /studies/{study_key}/rodadas/{round_key}/files	studies:read	200	Configurar
Baixar arquivo da rodada	GET /studies/{study_key}/rodadas/{round_key}/files/{filename}	studies:read	200 (bytes)	Configurar
Validar regras	POST /deck-rules/validate	studies:write	200	Regras de deck
Enviar regras	POST /deck-rules/uploads	studies:write	201	Regras de deck
Listar Cards do catálogo	GET /deck-rules/catalog	studies:read	200, lista	Regras de deck
Resolver Card	POST /deck-rules/catalog/{catalog_id}/resolve	studies:write	202 Operation	Regras de deck
Perfil da organização	GET/PATCH /deck-rules/profile	leitura/escrita	200	Regras de deck
Perfil do estudo	GET/PATCH /studies/{study_key}/deck-rules-profile	leitura/escrita	200	Regras de deck
Cards da rodada	GET/PUT /studies/{study_key}/rodadas/{round_key}/deck-rules	leitura/escrita	200	Regras de deck
Prévia do deck montado	POST /studies/{study_key}/rodadas/{round_key}/deck-rules/preview	studies:read	202 Operation	Regras de deck
Listar execuções	GET /studies/{study_key}/executions	executions:read	200, lista	Executar
Iniciar execução	POST /studies/{study_key}/executions	executions:write	202 Operation	Executar
Consultar execução	GET /executions/{execution_id}	executions:read	200 Execution	Executar
Parar execução	POST /executions/{execution_id}/stop	executions:write	202 Operation	Executar
Listar resultados mais recentes	GET /executions/{execution_id}/artifacts	executions:read	200, lista	Resultados
Listar coletas	GET /executions/{execution_id}/artifact-manifests	executions:read	200, lista	Resultados
Listar resultados de uma coleta	GET /executions/{execution_id}/artifact-manifests/{manifest_id}/artifacts	executions:read	200, lista	Resultados
Consultar um resultado	GET /executions/{execution_id}/artifacts/{artifact_id}	executions:read	200 Artifact	Resultados
Baixar um resultado	GET /executions/{execution_id}/artifacts/{artifact_id}/download	executions:read	200 (bytes), 409, 410 ou 503	Resultados
Listar pedidos	GET /operations	leitura do domínio	200, lista	Acompanhar pedidos
Acompanhar pedido	GET /operations/{operation_id}	leitura do domínio	200 Operation	Acompanhar pedidos
Cancelar pedido	POST /operations/{operation_id}/cancel	escrita do domínio	200 Operation	Acompanhar pedidos
Consultar webhook	GET /webhook	webhooks:read	200 ou 404	Webhooks
Configurar webhook	PUT /webhook	webhooks:write	200	Webhooks
Desligar webhook	DELETE /webhook	webhooks:write	200	Webhooks
Trocar segredo	POST /webhook/rotate-secret	webhooks:write	200 ou 404	Webhooks
Listar entregas	GET /webhook/deliveries	webhooks:read	200, lista	Webhooks
Refazer entrega	POST /webhook/deliveries/{delivery_id}/redeliver	webhooks:write	202 Operation	Webhooks