Seções da documentação

Trabalhos de simulação

As calculadoras respondem em uma requisição. Os simuladores não (uma resolução de onda completa leva de minutos a horas), por isso são enviados como trabalhos e consultados. Cada tipo de trabalho publica o seu contrato de parâmetros em /api/py/v1/jobs/types: tipo, unidade, faixa ou opções, padrão e obrigatoriedade de cada parâmetro, e os limites do seu plano. O formulário do navegador é montado a partir desse documento e o worker valida por ele, então leia-o em vez de copiar nomes de parâmetros desta página.

Endpoints

Endpoints de trabalhos
Endpoint	O que faz	Credencial
GET /api/py/v1/jobs/types	Cada tipo de trabalho de simulação, com os seus planos, o tempo máximo, os limites e os uploads.	Nenhuma
GET /api/py/v1/jobs/types/{job_type}	O contrato de parâmetros de um tipo de trabalho, em JSON Schema.	Nenhuma
POST /api/py/v1/jobs/estimate	Quanto um trabalho custaria e quanto tempo rodaria, sem enviá-lo.	Nenhuma
POST /api/py/v1/upload	Um formulário pré-assinado para o arquivo de entrada de um trabalho.	Chave de API ou sessão conectada
POST /api/py/v1/jobs	Enviar um trabalho de simulação.	Opcional: chave de API
GET /api/py/v1/jobs/{job_id}	O status e o progresso de um trabalho e, depois de concluído, o link do resultado.	A identidade que o enviou
GET /api/py/v1/jobs	Os trabalhos recentes do chamador, de todas as chaves da conta.	Chave de API ou sessão conectada

Enviar e consultar

Leia o contrato, envie o trabalho por POST com os seus params (e inputFileKeys para um arquivo enviado) e receba 202 com um jobId. Com uma chave, um envio é contabilizado como uma chamada na cota.

Consulte GET /api/py/v1/jobs/{jobId} com a mesma identidade que o enviou. O status traz progress, stage, finishedAt, elapsedSeconds, errorKind e, depois de concluído, uma resultUrl pré-assinada. GET /api/py/v1/jobs lista os seus trabalhos recentes, incluindo os enviados com qualquer chave da conta. A biblioteca Python consulta como o aplicativo web: job.wait() verifica na hora e depois a cada 2 s, 5 s e 15 s enquanto o trabalho continua.

Tipos de trabalho

13 tipos de trabalho. A lista de parâmetros de cada um está em /api/py/v1/jobs/types/{jobType}.

Tipos de trabalho
jobType	Simulador	Uploads
`antenna_sim`14 parâmetros	Simulador de antena de fio (NEC-2)	Nenhum
`emi_radiated`11 parâmetros	Estimador de emissões radiadas EMI	Nenhum
`eye_diagram`11 parâmetros	Diagrama ocular a partir dos parâmetros S	Obrigatório, até 1 × .s2p / .s4p
`fdtd_sparam`17 parâmetros	Simulador de linha de transmissão FDTD	Nenhum
`filter_monte_carlo`15 parâmetros	Análise de Monte Carlo de Filtro RF	Nenhum
`impedance_match`14 parâmetros	Sintetizador de correspondência de impedância de banda larga	Opcional, até 2 × .s2p / .s1p
`magnetics_optimizer`14 parâmetros	Otimizador de design magnético e de transformadores	Nenhum
`pdn_impedance`16 parâmetros	Analisador de impedância PDN e otimizador de capacitor de desacoplamento	Nenhum
`radar_detection`15 parâmetros	Desempenho de detecção de radar em Monte Carlo	Nenhum
`rf_cascade`8 parâmetros	Analisador de orçamento RF Cascade	Opcional, até 12 × .s2p
`sat_link_budget`14 parâmetros	Orçamento de links terrestres e de satélites	Nenhum
`smps_control_loop`36 parâmetros	Analisador de estabilidade do circuito de controle SMPS	Nenhum
`sparam_pipeline`3 parâmetros	Pipeline de análise de parâmetros S	Obrigatório, até 4 × .s1p / .s2p / .s3p / .s4p

Quanto um trabalho custaria

POST /api/py/v1/jobs/estimate recebe o corpo que um envio mandaria e responde com o ambiente de execução em que o trabalho rodaria, o tempo previsto, se ele cabe no orçamento desse ambiente e, no ambiente pago, os créditos que registraria. A estimativa nunca é cobrada, não precisa de chave e faz as mesmas verificações de um envio, então recusa exatamente quando um envio seria recusado. Os créditos são mostrados e registrados, mas ainda não são cobrados.

Quando uma requisição é recusada

Um envio é verificado contra o seu contrato antes de qualquer coisa entrar na fila ou ser cobrada. Uma requisição fora dele recebe um 400 que nomeia cada parâmetro com problema, não só o primeiro encontrado; nada entra na fila e nenhuma cota é consumida. Chaves de parâmetro desconhecidas são recusadas em vez de ignoradas.

Tipos de erro

Toda falha traz errorKind ao lado da mensagem, tanto em um envio recusado quanto em um trabalho que falhou depois de aceito. É um conjunto fechado; decida o tratamento por ele, e não pelo texto da mensagem, que é escrito para pessoas e pode mudar.

Tipos de erro
errorKind	Significado
invalid_request	Um parâmetro está faltando, tem o tipo errado, está fora da faixa, não é uma das opções declaradas ou não é um parâmetro deste tipo de trabalho. O corpo do 400 lista cada parâmetro com problema.
too_large	A requisição está dentro do contrato, mas além do que o ambiente de execução deste plano consegue rodar. Reduza o tamanho do problema.
not_available	A requisição pede um modo ou um recurso que este plano não inclui. A mensagem nomeia o que o plano inclui.
rate_limited	Um limite de trabalhos simultâneos ou uma cota mensal se esgotou. Traz Retry-After e, quando a cota é mensal, resetAt.
timeout	O trabalho excedeu o tempo máximo do seu tipo. Nada é cobrado por ele.
interrupted	A execução parou antes de terminar — um worker foi substituído ou uma tarefa foi interrompida. Nada é cobrado por ela.
result_expired	O trabalho foi concluído, mas o resultado não está mais guardado. O status continua completed e não traz resultUrl.
transient	O serviço não conseguiu aceitar nem verificar a requisição naquele momento. Nada entrou na fila nem foi cobrado; tente de novo.
fault	O serviço falhou durante o cálculo. A mensagem diz em qual etapa; nada é cobrado por ele.

Limites, duplicatas e tempos de vida

Concorrência

3 trabalhos na fila ou em execução ao mesmo tempo, por chamador. Acima disso, a API devolve 429 com Retry-After e um corpo que traz pending e limit.

Envios duplicados

Uma requisição idêntica do mesmo chamador em até 60 s devolve o trabalho existente, com o seu status real, de modo que um trabalho que já falhou volta como falho, com o motivo. Envie Idempotency-Bypass: true para executá-lo de novo mesmo assim.

Uploads

POST /api/py/v1/upload precisa de uma chave ou de uma sessão conectada e devolve um formulário POST pré-assinado válido por 5 minutos. No máximo 10 MB por arquivo, imposto pelo próprio formulário. Aceitos: .s1p .s2p .s3p .s4p .s6p .s8p .snp .csv .txt. O objeto enviado é guardado por 24 horas, então envie o trabalho que o usa no mesmo dia. 20 formulários por minuto por endereço.

Resultados

Dois prazos diferentes. resultExpiresAt é quando o próprio resultado some: 30 dias no plano gratuito, guardados por tempo indeterminado no Pro e no API. resultUrlExpiresIn é quanto dura a resultUrl pré-assinada: 15 minutos. Consulte de novo para obter um link novo; não guarde a URL em cache. Depois que o resultado some, o status continua completed, com o tipo result_expired e sem URL.

O que mudou para quem omite um parâmetro

Cada tipo de trabalho tem uma única definição dos seus parâmetros, e os valores de reserva dos próprios handlers deixaram de existir. Se você envia todos os campos, nada mudou. Se você omite um destes, o valor usado é diferente do anterior, e a resposta também.

Padrões alterados
jobType	Parâmetro	Antes	Agora
`rf_cascade`	`nfSpec_db`	10 dB	6 dB
`rf_cascade`	`inputPower_dbm`	−60 dBm	−70 dBm
`rf_cascade`	`bandwidth_hz`	1 MHz	10 MHz
`rf_cascade`	`stages`	"[]"	obrigatório — sem padrão
`smps_control_loop`	`toleranceDistribution`	uniform	gaussian
`filter_monte_carlo`	`freqCutoff`	1 MHz	1 GHz
`impedance_match`	`freqStart`	1 MHz	800 MHz
`impedance_match`	`freqStop`	100 MHz	1,2 GHz
`antenna_sim`	`freq (instant solve)`	145 MHz	146 MHz
`pdn_impedance`	`portX_mm`	centro da placa (boardWidth_mm / 2)	ponto a um terço (boardWidth_mm / 3)
`pdn_impedance`	`portY_mm`	centro da placa (boardLength_mm / 2)	ponto a um terço (boardLength_mm / 3)

Chaves de parâmetro desconhecidas eram descartadas e respondidas com um padrão. Agora são recusadas, e a recusa lista as chaves que o tipo de trabalho aceita.

Nos tipos de trabalho que fazem amostragem (filter_monte_carlo e os outros otimizadores), a semente aleatória é derivada do corpo que você envia, então o mesmo projeto enviado com chaves diferentes no corpo no corpo no corpo no corpo no corpo no corpo no corpo no corpo sorteia uma amostra diferente. Omitir um parâmetro e enviá-lo com o seu padrão são a mesma requisição para o solucionador, mas não o mesmo corpo; por isso uma execução feita pelo formulário web e outra feita por esta API podem diferir dentro do erro de amostragem. Envie randomSeed para fixar uma execução com exatidão.

Mudanças da versão de setembro de 2026

Comportamento que mudou para uma integração existente. Se você envia todos os parâmetros e verifica errorKind em vez do texto da mensagem, as únicas diferenças que deve notar são estas. As mudanças posteriores, e a data em que cada uma foi anunciada, estão no registro de alterações da API.

O que mudou

Chaves de parâmetro desconhecidas e valores fora da faixa são recusados no envio com um 400 que nomeia o parâmetro com problema, em vez de serem descartados ou limitados e respondidos mesmo assim.
11 padrões de parâmetros mudaram para quem omite o campo; veja a tabela acima.
Uma cota mensal esgotada agora é HTTP 402 (errorKind rate_limited) com Retry-After e resetAt, nunca um 401 e nunca um simples 429. Isso vale tanto para o mês da chave de API quanto para a cota dos modos de resolução FDTD.
Um upload agora precisa de uma sessão conectada ou de uma chave de API; uma requisição anônima recebe um 401 antes de qualquer coisa ser guardada. O ambiente gratuito anônimo perde por completo as duas ferramentas com arquivo de entrada (eye_diagram, sparam_pipeline), já que nenhuma roda sem um arquivo enviado.
Um trabalho enviado com uma chave de API agora pertence à conta dona da chave: ele é autorizado pelo dono, e não só pelo id da chave ou pelo IP de envio, e aparece na lista de trabalhos do painel do dono.
Um resultado concluído agora traz warnings e provenance (method, version, seed e as entradas normalizadas de fato usadas) ao lado dos valores calculados.
Toda falha — um envio recusado e um trabalho que falhou depois de aceito — agora traz errorKind. Veja o conjunto fechado acima.
Um trabalho cujo worker cai no meio da execução — substituído, ou com a tarefa interrompida — agora é marcado como falho com o tipo interrupted em vez de ficar travado, e qualquer cobrança por ele é liberada.
Um resultado é guardado exatamente pelo tempo que o seu registro diz: veja resultExpiresAt no cartão Resultados acima.
A topologia Auto do sintetizador de impedância agora compara as cinco topologias e devolve a de melhor perda de retorno no pior caso — antes ela sempre montava uma rede L, tanto no modo rápido quanto no padrão avançado.
O sintetizador de impedância agora respeita maxQ e componentSeries; os dois eram aceitos e ignorados em silêncio.
O ajuste aos valores padronizados da série E agora arredonda uma mantissa acima de cerca de 9,55 para cima, até o primeiro valor da década seguinte (9,9 nF → 10 nF), em vez de para baixo. Isso pode mudar o valor de um componente em um projeto de casamento de impedância ou em uma execução Monte Carlo de filtro para a mesma entrada.
As netlists SPICE exportadas da página de impedância agora trazem os valores padronizados (ajustados) dos componentes, não os ideais, com uma linha de cabeçalho que nomeia a série.
Os projetos de indutores de potência e de indutores acoplados agora são dimensionados a partir da indutância e da corrente de pico que você informa, em vez de derivados de outras entradas; os transformadores flyback e forward não mudam. Uma requisição cuja corrente de pico informada não é coerente com o ripple da indutância informada volta com um aviso ripple_exceeds_peak.
Nota de implantação: o validador da API foi implantado antes do worker durante este rollout, então um trabalho colocado na fila nesse intervalo cujo corpo trazia uma chave com erro de digitação — antes aceita em silêncio com um padrão — foi recusado no envio em vez de ser executado até o fim.

Enviar

curl -X POST https://rftools.io/api/py/v1/jobs \
  -H "X-API-Key: $RFTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "sat_link_budget",
    "params": {
      "latitude_deg": 40.7,
      "longitude_deg": -74,
      "frequency_ghz": 12
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

job = client.submit_job("sat_link_budget", {"latitude_deg": 40.7, "longitude_deg": -74, "frequency_ghz": 12})
job = job.wait(timeout=600)
print(job.status, job.result())

const response = await fetch("https://rftools.io/api/py/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jobType": "sat_link_budget",
    "params": {
      "latitude_deg": 40.7,
      "longitude_deg": -74,
      "frequency_ghz": 12
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "jobType": "sat_link_budget",
	  "params": {
	    "latitude_deg": 40.7,
	    "longitude_deg": -74,
	    "frequency_ghz": 12
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/jobs", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

application/json

{
  "jobId": "6f1c2d4e-…",
  "status": "queued",
  "queuePosition": 1,
  "queueTotal": 1
}

Na fila. Consulte o jobId.

{
  "errorKind": "invalid_request",
  "detail": [
    {
      "param": "frequency_ghz",
      "value": 900,
      "reason": "Frequency (frequency_ghz) must be between 0.1 and 100 GHz (got 900 GHz).",
      "allowed": "0.1 to 100 GHz"
    },
    {
      "param": "longitude_deg",
      "value": null,
      "reason": "Site Longitude (longitude_deg) is required.",
      "allowed": null
    }
  ]
}

Todos os parâmetros fora do contrato, de uma vez. Nada entrou na fila.

{
  "detail": "You already have 3 jobs queued or running, and the limit is 3. Wait for one to finish.",
  "pending": 3,
  "limit": 3,
  "errorKind": "rate_limited"
}

Trabalhos demais ao mesmo tempo, com Retry-After.

Consultar

curl https://rftools.io/api/py/v1/jobs/JOB_ID \
  -H "X-API-Key: $RFTOOLS_API_KEY"

import os

import httpx

response = httpx.get(
    "https://rftools.io/api/py/v1/jobs/JOB_ID",
    headers={"X-API-Key": os.environ["RFTOOLS_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch("https://rftools.io/api/py/v1/jobs/JOB_ID", {
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
  },
});
console.log(response.status, await response.json());

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://rftools.io/api/py/v1/jobs/JOB_ID", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

Estimar, sem enviar

curl -X POST https://rftools.io/api/py/v1/jobs/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "fdtd_sparam",
    "params": {
      "traceW": 0.42,
      "subH": 0.51,
      "solveMode": "express"
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

est = client.estimate_job("fdtd_sparam", {"traceW": 0.42, "subH": 0.51, "solveMode": "express"})
print(est.lane, est.wall_seconds, est.within_budget)

const response = await fetch("https://rftools.io/api/py/v1/jobs/estimate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jobType": "fdtd_sparam",
    "params": {
      "traceW": 0.42,
      "subH": 0.51,
      "solveMode": "express"
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{
	  "jobType": "fdtd_sparam",
	  "params": {
	    "traceW": 0.42,
	    "subH": 0.51,
	    "solveMode": "express"
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/jobs/estimate", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}