> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/sdks/python/jobs-triggers-capabilities.md). # Jobs, triggers & capabilities Python SDK reference for async jobs, deployments, triggers, data sources, and the capability plane — every AlgentaClient method with its endpoint and return type. This reference covers the `AlgentaClient` methods for long-running work (async jobs and deployments), event-driven automation (triggers and data sources), and the capability plane (providers, bindings, the capability catalog, execution, and skills). Every method is a faithful client over the `/v1` HTTP contract; the async client `AsyncAlgentaClient` exposes the same names to `await`. ```python import os from decision_engine import AlgentaClient client = AlgentaClient( api_key=os.environ["ALGENTA_API_KEY"], base_url="https://api.algenta.ai", # or http://localhost:8000 self-hosted ) ``` ## Async jobs | Method | HTTP | Returns | | ------------------------------------------------------- | ------------------------------- | ------- | | `submit_job(request=None, callback_url=None, **kwargs)` | `POST /v1/jobs` | `dict` | | `get_job(job_id)` | `GET /v1/jobs/{job_id}` | `dict` | | `get_job_result(job_id)` | `GET /v1/jobs/{job_id}/result` | `dict` | | `list_jobs(*, page=1, limit=25, status=None)` | `GET /v1/jobs/list` | `dict` | | `cancel_job(job_id)` | `POST /v1/jobs/{job_id}/cancel` | `dict` | | `test_webhook_delivery(callback_url)` | `POST /v1/webhooks/test` | `dict` | | `poll_job(job_id, timeout=300.0, poll_interval=2.0)` | client-side helper | `dict` | * `submit_job` accepts a job `request` body (or keyword fields) and an optional `callback_url` webhook for completion. It returns immediately with a job id. * `poll_job` is a convenience loop: it polls `get_job` until the job reaches `completed` (then returns `get_job_result`) or raises if it ends `failed`/`cancelled` or exceeds `timeout`. * `test_webhook_delivery` sends a test payload to a `callback_url` so you can confirm your endpoint receives deliveries before wiring it to a real job. ## Deployments | Method | HTTP | Returns | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------------------------- | | `list_deployment_regions()` | `GET /v1/deployments/regions` | `DeploymentRegionsResult` | | `get_deployment()` | `GET /v1/deployments` | `DeploymentResult \| None` | | `create_deployment(*, provider="algenta_shared", region="algenta-shared", config=None, billing_markup_pct=20.0)` | `POST /v1/deployments` | `DeploymentResult` | | `delete_deployment(deployment_id)` | `DELETE /v1/deployments/{deployment_id}` | `DeploymentDeleteResult` | | `get_deployment_cost(deployment_id)` | `GET /v1/deployments/{deployment_id}/cost` | `DeploymentCostResult` | * `get_deployment` returns your current deployment, or `None` if none exists yet. * `list_deployment_regions` enumerates the regions you can pass to `create_deployment`. ## Triggers | Method | HTTP | Returns | | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---------------------- | | `register_trigger(*, name, condition, simulation_template, webhook_url=None, execution_webhook_url=None, auto_execute=False, description=None)` | `POST /v1/triggers` | `TriggerSummaryResult` | | `list_triggers(*, status="all", page=None, limit=None)` | `GET /v1/triggers` | `TriggerListResult` | | `fire_trigger(trigger_id, *, force=False)` | `POST /v1/triggers/{trigger_id}/fire` | `TriggerFireResult` | | `pause_trigger(trigger_id, *, paused=True)` | `PATCH /v1/triggers/{trigger_id}/pause` | `TriggerPauseResult` | | `delete_trigger(trigger_id)` | `DELETE /v1/triggers/{trigger_id}` | `TriggerDeleteResult` | * `register_trigger` binds a `condition` to a `simulation_template`; when the condition matches, the trigger runs the template and (if `auto_execute=True`) executes the recommended action. `webhook_url` and `execution_webhook_url` receive the results. * `fire_trigger` runs a trigger on demand; `force=True` runs it even if its condition is not currently met. `pause_trigger` toggles a trigger active/paused via `paused`. ## Data sources | Method | HTTP | Returns | | ------------------------------------------------------------- | ------------------------------------ | -------------------------- | | `register_source(source=None, *, description=None, **kwargs)` | `POST /v1/sources/register` | `SourceRegistrationResult` | | `refresh_source(dataset_id)` | `POST /v1/data/{dataset_id}/refresh` | `SourceRegistrationResult` | * `register_source` registers an external data source (passed as a `source` mapping or keyword fields) as a governed dataset. * `refresh_source` re-pulls the latest data for an already-registered dataset by its `dataset_id`. ## Capability providers | Method | HTTP | Returns | | -------------------------------------- | -------------------------------------------- | -------------------------------- | | `list_capability_providers()` | `GET /v1/capability-providers` | `list[CapabilityProviderResult]` | | `get_capability_provider(provider_id)` | `GET /v1/capability-providers/{provider_id}` | `CapabilityProviderResult` | | `list_mcp_providers()` | `GET /v1/capability-providers` (filtered) | `list[CapabilityProviderResult]` | * `list_mcp_providers` is a client-side convenience that returns only providers whose `provider_type` is `mcp_provider`. ## Capability bindings | Method | HTTP | Returns | | ----------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------- | | `list_capability_bindings(*, provider_id=None, scope=None)` | `GET /v1/capability-bindings` | `list[CapabilityBindingResult]` | | `create_capability_binding(request)` | `POST /v1/capability-bindings` | `CapabilityBindingResult` | | `get_capability_binding(binding_id)` | `GET /v1/capability-bindings/{binding_id}` | `CapabilityBindingResult` | | `update_capability_binding(binding_id, request)` | `PATCH /v1/capability-bindings/{binding_id}` | `CapabilityBindingResult` | | `delete_capability_binding(binding_id)` | `DELETE /v1/capability-bindings/{binding_id}` | `None` | | `preview_test_capability_binding(request)` | `POST /v1/capability-bindings/test` | `CapabilityBindingTestResult` | | `test_capability_binding(binding_id)` | `POST /v1/capability-bindings/{binding_id}/test` | `CapabilityBindingTestResult` | | `preview_discover_capability_binding(request)` | `POST /v1/capability-bindings/discover` | `CapabilityDiscoverResult` | | `discover_capability_binding(binding_id)` | `POST /v1/capability-bindings/{binding_id}/discover` | `CapabilityDiscoverResult` | | `start_capability_authorization(binding_id, request)` | `POST /v1/capability-bindings/{binding_id}/authorize/start` | `CapabilityAuthorizationStartResult` | | `complete_capability_authorization(binding_id, request)` | `POST /v1/capability-bindings/{binding_id}/authorize/complete` | `CapabilityAuthorizationCompleteResult` | * The `preview_*` methods validate or discover against an unsaved `request` body; the id-taking variants act on a saved binding. * `start_capability_authorization` / `complete_capability_authorization` drive an OAuth-style handshake for bindings that need delegated authorization. ## Capability catalog and execution | Method | HTTP | Returns | | ----------------------------------------------------------------------- | -------------------------------------- | ------------------------------------ | | `list_capabilities(*, kinds=None, provider_ids=None, binding_ids=None)` | `GET /v1/capabilities` | `list[CapabilityCatalogEntryResult]` | | `get_capability(capability_id, *, include_instruction=False)` | `GET /v1/capabilities/{capability_id}` | `CapabilityCatalogEntryResult` | | `route_capabilities(request)` | `POST /v1/capabilities/route` | `CapabilityRoutePlanResult` | | `execute_capability(request)` | `POST /v1/capabilities/execute` | `CapabilityExecutionResult` | | `record_capability_outcome(request)` | `POST /v1/capabilities/outcomes` | `CapabilityOutcomeRecordResult` | * `route_capabilities` asks the plane which capability best fits an intent; `execute_capability` runs a chosen capability; `record_capability_outcome` reports back how it went, feeding future routing. ## Skills | Method | HTTP | Returns | | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------ | | `list_skills()` | `GET /v1/capabilities` (`kinds=["skill"]`) | `list[CapabilityCatalogEntryResult]` | | `enable_skill(*, skill_name, instruction, description=None, tags=None, artifact_affinities=None, execution_owner="client_managed")` | `POST /v1/capability-bindings` | `CapabilityDiscoverResult` | | `disable_skill(binding_id)` | `DELETE /v1/capability-bindings/{binding_id}` | `None` | * `enable_skill` is a shorthand: it creates an instruction-only skill capability binding from your `skill_name` and `instruction`, then discovers it so it is ready to route. * `disable_skill` removes the skill by deleting its binding. {% hint style="info" %} Skills and MCP providers are two views of the same capability plane. `list_skills` and `list_mcp_providers` are convenience filters over `list_capabilities` and `list_capability_providers`; the underlying binding, routing, and execution methods are identical. {% endhint %} ## Example: submit a job and wait for the result ```python import os from decision_engine import AlgentaClient client = AlgentaClient(api_key=os.environ["ALGENTA_API_KEY"], base_url="https://api.algenta.ai") job = client.submit_job({ "mode": "auto", "scenario": { "name": "Fleet reorder", "variables": {"demand": {"low": 1000, "high": 4000}}, "objective": "maximize_net_value", }, "runs": 50000, }) print(job["job_id"], job["status"]) result = client.poll_job(job["job_id"], timeout=120.0, poll_interval=2.0) print(result["status"]) ``` ## Example: route and execute a capability ```python import os from decision_engine import AlgentaClient client = AlgentaClient(api_key=os.environ["ALGENTA_API_KEY"], base_url="https://api.algenta.ai") # Discover what is available, then let the plane pick the best fit. catalog = client.list_capabilities(kinds=["skill", "tool"]) print(len(catalog), "capabilities") plan = client.route_capabilities({"objective": "Send a summary to the on-call channel"}) execution = client.execute_capability({ "capability_id": plan.selected_capability_id, "binding_id": plan.selected_binding_id, "input": {"message": "3 incidents open; remediation order attached."}, }) client.record_capability_outcome({ "capability_id": execution.capability_id, "provider_id": execution.provider_id, "binding_id": execution.binding_id, "success": execution.status == "succeeded", "result_status": execution.status, }) ``` ## Related references {% content-ref url="/pages/HOwT1VAS0XihjiBPZnj1" %} [Account & control plane](/sdks/python/account-and-control-plane.md) {% endcontent-ref %} {% content-ref url="/pages/hSwE3Yg9Tyg5c8xWXEZO" %} [Run an async job](/guides/async-jobs.md) {% endcontent-ref %} {% content-ref url="/pages/2P0FmT4EqEhuumZOxjAJ" %} [Route & execute capabilities](/guides/capabilities.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.algenta.ai/sdks/python/jobs-triggers-capabilities.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.