Calling an external API
Make an HTTP call to an instrument or service from a skill, authenticate with a stored secret, and keep the response with the project.
api_request
api_requestapi_request(url, method="GET", *, json_body=None, params=None, headers=None, save_name=None,
save_to_project=False, export=False, timeout=30, auth_secret=None)Calls url and returns a result dict. It never raises: a timeout, a connection error or a non-2xx status comes back as success: False. Check the result and raise when the step should fail.
| Argument | Meaning |
|---|---|
url | The full request URL. Pass the address in as a skill input so the same skill can talk to different instruments. |
method | "GET", "POST", "PUT", ... |
json_body | A value sent as the JSON body. |
params | Query-string parameters (dict). |
headers | Request headers (dict). |
timeout | Seconds before the request is abandoned. |
auth_secret | The name of a secret to send as Authorization: Bearer <value>. It replaces any Authorization header in headers. |
save_name | A file name (no extension) for the saved response. Without it nothing is saved. |
save_to_project | Deprecated; prefer export. With save_name: write the response to data/api/<execution_id>/<save_name>.json in the project, which syncs with it. |
export | With save_name: upload the response to your lab's own storage bucket, when data export is configured on the rig. |
The result:
| Key | Value |
|---|---|
success | True when the request returned a 2xx status. |
status | The HTTP status code (None when the request failed). |
data | The parsed JSON body, or the text when the body is not JSON. |
error | Why it failed (failures only). |
saved_path | Where the response was saved (when saved). |
t | When the request started (epoch seconds). |
def read_absorbance(plate_id: str = "P1", *, base_url: str):
res = api_request(f"{base_url}/api/v1/read", method="POST", json_body={"plate": plate_id},
auth_secret="PLATE_READER_TOKEN", save_name=f"read_{plate_id}", export=True)
if not res["success"]:
raise RuntimeError(f"plate reader: {res['error']}")
return {"success": True, "values": res["data"]}Each call writes one line to the skill's log with the method, the URL and the status.
get_secret
get_secretget_secret(name, default=None)Returns the value of the secret stored under name, or default when it is not set. It never raises. Use it when a token goes somewhere other than a bearer header.
Secrets in the cloud
Secrets are set on a lab machine (see Secrets). In the cloud there is no secret store: get_secret returns default, and api_request with auth_secret does not send the request and returns success: False with the reason. A skill that calls an authenticated instrument therefore needs an is_sim_mode() branch, or a check of the result, to run in the cloud simulator.
Handling credentials
- Never write a token in skill code or pass one as a workflow input. Store it as a secret and use
auth_secretorget_secret. - Never log, return or send a secret value.
- Never put a token in a URL or a query string: URLs are written to the log.
Updated 9 days ago