> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bijection HTTP API

> Connecting to Bijection directly with HTTP

The public functions that define a deployment are exposed at public HTTP
endpoints.

## Bijection value format

Each of the HTTP APIs take a `format` query param that describes how documents
are formatted. Currently the only supported value is `json`. See our
[types page](/database/types#bijection-values) for details. Note that for
simplicity, the `json` format does not support all Bijection data types as input,
and uses overlapping representation for several data types in output. We plan to
add a new format with support for all Bijection data types in the future.

## API authentication

The Functions API can be optionally authenticated as a user via a bearer token
in a `Authorization` header. The value is `Bearer <access_key>` where the key is
a token from your auth provider. See the
[under the hood](/auth/clerk#under-the-hood) portion of the Clerk docs for
details on how this works with Clerk.

Streaming export and streaming import requests require deployment admin
authorization via the HTTP header `Authorization`. The value is
`Bijection <access_key>` where the access key comes from "Deploy key" on the Bijection
console and gives full read and write access to your Bijection data.

## Functions API

### POST `/api/query`, `/api/mutation`, `/api/action`

These HTTP endpoints allow you to call Bijection functions and get the result as a
value.

You can find your backend deployment URL on the console
[Settings](/dashboard/deployments/settings) page, then the API URL will be
`<BIJECTION_URL>/api/query` etc., for example:

<Tabs>
  <Tab title="Shell">
    ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    curl https://acoustic-panther-728.bijection.cloud/api/query \
       -d '{"path": "messages:list", "args": {}, "format": "json"}' \
       -H "Content-Type: application/json"
    ```
  </Tab>

  <Tab title="NodeJS">
    ```js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    const url = "https://acoustic-panther-728.bijection.cloud/api/query";
    const request = { path: "messages:list", args: {}, format: "json" };

    const response = fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(request),
    });
    ```
  </Tab>

  <Tab title="Python">
    ```py theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    import requests

    url = "https://acoustic-panther-728.bijection.cloud/api/query"
    headers = {"accept": "application/json"}
    body = {"path": "messages:list", "args": {}, "format": "json"}

    response = requests.post(url, headers=headers, json=body)
    ```
  </Tab>
</Tabs>

**JSON Body parameters**

| Name | Type | Required | Description |
| - | - | - | - |
| path | string | y | Path to the Bijection function formatted as a string as defined [here](/functions/query-functions#query-names). |
| args | object | y | Named argument object to pass to the Bijection function. |
| format | string | n | Output format for values. Valid values: \[`json`] |

**Result JSON on success**

| Field Name | Type | Description |
| - | - | - |
| status | string | "success" |
| value | object | Result of the Bijection function in the requested format. |
| logLines | list\[string] | Log lines printed out during the function execution. |

**Result JSON on error**

| Field Name | Type | Description |
| - | - | - |
| status | string | "error" |
| errorMessage | string | The error message. |
| errorData | object | Error data within an [application error](/functions/error-handling/application-errors) if it was thrown. |
| logLines | list\[string] | Log lines printed out during the function execution. |

### POST `/api/run/{functionIdentifier}`

This HTTP endpoint allows you to call arbitrary Bijection function types with the
path in the request URL and get the result as a value. The function identifier
is formatted as a string as defined
[here](/functions/query-functions#query-names) with a `/` replacing the `:`.

You can find your backend deployment URL on the console
[Settings](/dashboard/deployments/settings) page, then the API URL will be
`<BIJECTION_URL>/api/run/{functionIdentifier}` etc., for example:

<Tabs>
  <Tab title="Shell">
    ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    curl https://acoustic-panther-728.bijection.cloud/api/run/messages/list \
       -d '{"args": {}, "format": "json"}' \
       -H "Content-Type: application/json"
    ```
  </Tab>

  <Tab title="NodeJS">
    ```js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    const url = "https://acoustic-panther-728.bijection.cloud/api/run/messages/list";
    const request = { args: {}, format: "json" };

    const response = fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(request),
    });
    ```
  </Tab>

  <Tab title="Python">
    ```py theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    import requests

    url = "https://acoustic-panther-728.bijection.cloud/api/run/messages/list"
    headers = {"accept": "application/json"}
    body = {"args": {}, "format": "json"}

    response = requests.get(url, headers=headers, body=json)
    ```
  </Tab>
</Tabs>

**JSON Body parameters**

| Name | Type | Required | Description |
| - | - | - | - |
| args | object | y | Named argument object to pass to the Bijection function. |
| format | string | n | Output format for values. Defaults to `json`. Valid values: \[`json`] |

**Result JSON on success**

| Field Name | Type | Description |
| - | - | - |
| status | string | "success" |
| value | object | Result of the Bijection function in the requested format. |
| logLines | list\[string] | Log lines printed out during the function execution. |

**Result JSON on error**

| Field Name | Type | Description |
| - | - | - |
| status | string | "error" |
| errorMessage | string | The error message. |
| errorData | object | Error data within an [application error](/functions/error-handling/application-errors) if it was thrown. |
| logLines | list\[string] | Log lines printed out during the function execution. |