> For the complete documentation index, see [llms.txt](https://docs.urbit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.urbit.org/urbit-os/kernel/iris/tasks.md).
# Iris API Reference
Iris API reference - HTTP client tasks for making requests, canceling requests, and receiving HTTP responses.
This document details the tasks used by Iris. Iris only has three tasks besides the standard vane tasks: [`%request`](#request), [`%cancel-request`](#cancel-request), and [`%receive`](#receive). The `%receive` task is only sent to Iris by the runtime, so you're likely to only use `%request` and `%cancel-request`.
## `%request`
```hoon
[%request =request:http =outbound-config]
```
Fetch a remote HTTP resource.
The [$request:http](/urbit-os/kernel/eyre/data-types.md#requesthttp) is the request itself and contains the HTTP method, the fully qualified target URL, a list of HTTP headers to be included and maybe the data for the body of the request.
The [`$outbound-config`](/urbit-os/kernel/iris/data-types.md#outbound-config) specifies the number of redirects to follow before failing and the number of retries to attempt before giving up. The default values are `5` and `3` respectively. As of writing, **retries and auto-following redirects are not implemented**, so what you specify here is irrelevant and you can just use the bunt value of `$outbound-config`.
#### Returns
Iris returns a `%http-response` gift in response to a `%request` task. A `%response` gift looks like:
```hoon
[%http-response =client-response]
```
The [$client-response](/urbit-os/kernel/iris/data-types.md#client-response) contains the HTTP response from the server including the status code, HTTP headers and any data along with its mime type.
The `$client-response` structure specifies three kinds of responses - `%progress`, `%finished` and `%cancel`. The `%progress` response would contain each chunk of the message as it came in, `%finished` would contain the final assembled message from Vere's buffer, and `%cancel` would be sent if the runtime cancels the request.
Note that neither `%progress` partial messages nor `%cancel` responses have been implemented in Vere at the time of writing, so **you will only ever receive a single `%http-response` gift with a `%finished`** **`$client-response`**. If the request fails for some reason, you'll still get an empty `%finished` `$client-response` with a `504` status code.
#### Example
See the [Example](/urbit-os/kernel/iris/example.md) document.
## `%cancel-request`
```hoon
[%cancel-request ~]
```
Cancel a previous request to fetch a remote HTTP resource.
A `%cancel-request` task does not take any arguments, the [request](#request) to cancel is determined implicitly.
#### Returns
Iris does not return any gift in response to a `%cancel-request` task. You will also not receive any gift back from the original `%request` task you've cancelled.
## `%receive`
```hoon
[%receive id=@ud =http-event:http]
```
Receives HTTP data from outside. This task is sent to Iris by the runtime, you would not use it manually.
The `.id` is a sequential ID for the event and the [$http-event:http](/urbit-os/kernel/eyre/data-types.md#http-eventhttp) contains the HTTP headers and data.
***
## Gifts
The complete `$gift:iris` union:
```hoon
+$ gift
$% [%request id=@ud request=request:http]
[%cancel-request id=@ud]
[%http-response =client-response]
==
```
* `%request` - An outbound HTTP request, given to Unix to perform. Note this shares a name with the [`%request`](#request) *task*: the task is how a vane asks Iris to fetch something, and the gift is how Iris asks Unix to do it.
* `%cancel-request` - Tells Unix to cancel a previously given `%request`. The same naming applies as above.
* `%http-response` - The result, given back to whoever sent the [`%request`](#request) task, as a [`$client-response`](/urbit-os/kernel/iris/data-types.md#client-response).
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.urbit.org/urbit-os/kernel/iris/tasks.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.