Formlabs Developers
Download PreForm Insider to start developing with the PreForm API.
Version v1.0.0-alpha (latest)

Operations

Poll and manage the long-running operations started by endpoints called with ?async=true. /v1/operation/get/ returns one operation's status and, once finished, its result. See the Asynchronous requests section of the introduction.

Get one operation's status and result#

GET/v1/operation/get/

Returns the full record of one operation started by a ?async=true request: its status, its progress, and, once status is SUCCEEDED or FAILED, the result the originating endpoint would have returned synchronously. This is the URL returned in operation_url (and the Location header) of every 202 Accepted response.

With mode=oneshot, a finished operation's record is deleted after this response, so the result can be fetched exactly once and needs no separate /v1/operation/delete/ call. An IN_PROGRESS operation is never deleted. The default, mode=persistent, never deletes.

Error codes#

HTTPerror.codeCause
400MISSING_QUERY_PARAMETERNo operation_id query parameter was given.
400INVALID_QUERY_PARAMETERmode is present but not oneshot or persistent.
404NOT_FOUNDNo operation with that id exists (never started, deleted, or fetched with mode=oneshot, or the server restarted).

Query parameters

  • operation_idstring (uuid)Required

    Id of the operation, as received in operation_id from the 202 Accepted response that started it.

  • modestring

    Whether fetching a finished operation deletes its record (oneshot) or keeps it (persistent, the default).

    Defaults to "persistent"

    One of:

    oneshot
     
    persistent
     

ReturnsOperationWithResult

  • idstring (uuid)Required

    The operation's id, as returned in operation_id when it was started.

  • statusenum OperationStatusRequired

    The current state of a long-running operation.

    Currently one of the following; more may be added:

    IN_PROGRESS
    The operation has not finished yet.
    SUCCEEDED
    The operation finished successfully.
    FAILED
    The operation finished with an error. The error envelope is available in the result field of /v1/operation/get/. /v1/operation/list/ reports the status only.
  • progressnumber (float)Required

    Progress of the operation, from 0.0 to 1.0.

  • resultobject

    Present once status is SUCCEEDED or FAILED, absent while IN_PROGRESS. On success this is the JSON body the originating endpoint documents as its 200 response. On failure it is the standard error envelope (error.code, error.message). Endpoints whose synchronous success response has no body leave result absent even after success.

The operation's current record.

GET/v1/operation/get/
Python
from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.get_operation(
        operation_id="3fa85f64-5717-4562-b3fc-2c963f66afa6",
    )
Terminal
curl "http://localhost:44388/v1/operation/get/?operation_id=3fa85f64-5717-4562-b3fc-2c963f66afa6"
Response
JSON
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "IN_PROGRESS",
  "progress": 0.42
}
JSON
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "SUCCEEDED",
  "progress": 1,
  "result": {
    "job_id": "8f14e45f-ceea-467f-a34e-9b6d2d7a90ae"
  }
}
JSON
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "FAILED",
  "progress": 1,
  "result": {
    "error": {
      "code": "OPERATION_FAILED",
      "message": "Cannot print: the printer is busy"
    }
  }
}

List operations#

POST/v1/operation/list/

List all in-progress, succeeded, and failed operations started by ?async=true requests since this server was launched. Operations are not persisted across server restarts. An optional operations array filters the results to specific operation ids. Only statuses are reported. Use /v1/operation/get/ to retrieve an operation's result.

Error codes#

HTTPerror.codeCause
404NOT_FOUNDAn id in operations does not correspond to any known operation.

Request bodyobject

  • operationsarray of string (uuid)s

    Operation ids to return, as received in operation_id from the 202 Accepted response that started each one. Omitting this field, or sending an empty array, selects every known operation.

Returnsobject

  • countintegerRequired

    Number of operations in the response.

  • operationsarray of OperationsRequired
    Show child attributes
    • idstring (uuid)Required

      The operation's id, as returned in operation_id when it was started.

    • statusenum OperationStatusRequired

      The current state of a long-running operation.

      Currently one of the following; more may be added:

      IN_PROGRESS
      The operation has not finished yet.
      SUCCEEDED
      The operation finished successfully.
      FAILED
      The operation finished with an error. The error envelope is available in the result field of /v1/operation/get/. /v1/operation/list/ reports the status only.
    • progressnumber (float)Required

      Progress of the operation, from 0.0 to 1.0.

The requested operations, or every known operation if operations was omitted, empty, or malformed.

POST/v1/operation/list/
Python
from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.list_operations()
Terminal
curl -X POST "http://localhost:44388/v1/operation/list/" \
  -H "Content-Type: application/json" \
  -d '{}'
Python
from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.list_operations(
        operations=["7c9e6679-7425-40de-944b-e07fc1f90ae7"],
    )
Terminal
curl -X POST "http://localhost:44388/v1/operation/list/" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ]
  }'
Response
JSON
{
  "count": 1,
  "operations": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "IN_PROGRESS",
      "progress": 0.42
    }
  ]
}

Delete operations#

DELETE/v1/operation/delete/

Removes one or more operation records from the server. Operations are validated before any are deleted: if any requested operation does not exist, or is still IN_PROGRESS, nothing is deleted.

Error codes#

HTTPerror.codeCause
400JSON_PARSE_ERRORThe request body is not a valid JSON object.
400JSON_SCHEMA_MATCH_ERRORoperations is missing, empty, or not an array of strings, or an unrecognized field is present.
404NOT_FOUNDAn id in operations does not correspond to any known operation. Nothing was deleted.
409OPERATION_IN_PROGRESSAn operation in operations is still IN_PROGRESS. Nothing was deleted.

Request bodyobject

  • operationsarray of string (uuid)sRequired

    Ids of the operations to delete, as received in operation_id when each was started.

    At least 1 items.

Returnsno body

    The operations were deleted. The response has no body.

    DELETE/v1/operation/delete/
    Python
    from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    preform.delete_operations(
        operations=["7c9e6679-7425-40de-944b-e07fc1f90ae7"],
    )
    Terminal
    curl -X DELETE "http://localhost:44388/v1/operation/delete/" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ]
  }'
    Response
    No response body.
    Feedback & Bug Reports