# Create task URL: https://docs.hanzo.ai/docs/openapi/git/post-runner-task > Hands the runner a job to execute, if its pool has one, and answers immediately either way. `POST /v1/runner/task` > [Git →](https://docs.hanzo.ai/docs/openapi/git) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | -------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/runner/task` | | **Method** | `POST` | | **Operation** | `post_runner_task` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Hands the runner a job to execute, if its pool has one, and answers immediately either way. A runner sends the queue version it last saw; when it matches, nothing has been queued since and no lease transaction is opened. ## Request 3 fields, body `application/json` (required). | Field | In | Type | Required | Description | | ---------------- | ------ | --------------- | -------- | ----------------------------------------------- | | `x-runner-uuid` | header | string | — | | | `x-runner-token` | header | string | — | | | `queue` | body | integer (int64) | — | Queue is the queue version the runner last saw. | ## Response | Status | Body | Meaning | | --------- | --------------- | ------- | | `200` | runner.TaskOut | ok | | `default` | problem-details | refused | `200` body — 38 fields. | Field | In | Type | Always | Description | | ------------------------------- | ---- | --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | `queue` | body | integer (int64) | — | Queue is the forge's current queue version, to ask against next time. | | `task` | body | runner.Task | — | | | `task.context` | body | runner.Context | — | | | `task.context.actions_url` | body | string | — | ActionsURL is where act fetches an action repository from when a step names one. | | `task.context.actor` | body | string | — | Actor is who caused the run. | | `task.context.api_url` | body | string | — | APIURL is where the job reaches the forge's API. | | `task.context.base_ref` | body | string | — | BaseRef is the target branch of a pull request, empty otherwise. | | `task.context.event` | body | string | — | Event is the webhook payload that triggered the run, as opaque JSON. | | `task.context.event_name` | body | string | — | EventName is what triggered the run, e.g. "push". | | `task.context.head_ref` | body | string | — | HeadRef is the source branch of a pull request, empty otherwise. | | `task.context.job` | body | string | — | Job is which job of the workflow document this task is. | | `task.context.ref` | body | string | — | Ref is the full ref the run is for, e.g. "refs/heads/main". | | `task.context.ref_name` | body | string | — | RefName is that ref without its refs/heads/ or refs/tags/ prefix. | | `task.context.ref_type` | body | string | — | RefType is "branch" or "tag". | | `task.context.repository` | body | string | — | Repository is "\/\". | | `task.context.repository_owner` | body | string | — | RepositoryOwner is the owner half of it. | | `task.context.retention_days` | body | string | — | RetentionDays is how long the run's artifacts are kept, as a number in a string because that is what an expression reads. | | `task.context.run_attempt` | body | string | — | RunAttempt is which attempt of that run this is, counting from 1. | | `task.context.run_id` | body | string | — | RunID identifies the run this task belongs to. | | `task.context.run_number` | body | string | — | RunNumber is the run's position in its repository, counting from 1. | | `task.context.runtime_token` | body | string | — | RuntimeToken authorizes the job against the actions runtime: artifacts, the cache. | | `task.context.server_url` | body | string | — | ServerURL is the forge's own origin, as a link in a log points at it. | | `task.context.sha` | body | string | — | Sha is the commit being run, in full. | | `task.context.token` | body | string | — | Token is the job's credential against the forge's own API — github.token in an expression. | | `task.id` | body | integer (int64) | — | ID identifies this task on every later state and log report. | | `task.needs` | body | runner.Need\[] | — | Needs is what the jobs this one depends on produced. | | `task.needs[].job` | body | string | — | Job is the depended-on job's id in the workflow. | | `task.needs[].outputs` | body | runner.Pair\[] | — | Outputs are the values it published. | | `task.needs[].outputs[].name` | body | string | — | Name is what the value is filed under. | | `task.needs[].outputs[].value` | body | string | — | Value is the value itself, always a string on this wire. | | `task.needs[].result` | body | string | — | Result is how it finished. | | `task.secrets` | body | runner.Pair\[] | — | Secrets are the values masked out of the log and exposed as secrets.\*. | | `task.secrets[].name` | body | string | — | Name is what the value is filed under. | | `task.secrets[].value` | body | string | — | Value is the value itself, always a string on this wire. | | `task.vars` | body | runner.Pair\[] | — | Vars are the values exposed as vars.\*. | | `task.vars[].name` | body | string | — | Name is what the value is filed under. | | `task.vars[].value` | body | string | — | Value is the value itself, always a string on this wire. | | `task.workflow` | body | string | — | Workflow is the workflow document verbatim. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo runner task ``` **SDK** **.ts** ```ts import { Configuration, GitApi } from 'hanzoai'; const api = new GitApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.postRunnerTask({ queue: 0 }); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import GitApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = GitApi(client).post_runner_task(queue=0) ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.GitAPI.PostRunnerTask(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, git_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = git_api::post_runner_task(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.GitApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new GitApi(client).postRunnerTask(); ``` **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/runner/task \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "queue": 0 }' ``` **MCP** MCP reaches **git** through the `git` tool, which names its 38 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them: ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "describe", "arguments": { "op": "list_git_keys" } } }' ``` --- [Git API](https://docs.hanzo.ai/docs/openapi/git) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)