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

# Make your first HTTP request

> Read your project list from your own backend using the IQRush MCP HTTP API. You need a valid bearer access token obtained for your integration and the matching environment.

Read your project list from your own backend using the IQRush MCP HTTP API. Complete [authentication](/developers/guides/04-authentication) first if your integration does not yet have an access token. This page checks the connection and selects the IDs used by the [report starter](/developers/guides/24-report-starter).

## Choose the base URL

The production HTTP base documented for this service is:

```text theme={null}
https://api.prod.gso.iqrush.ai/api/mcp
```

The remote MCP transport adds another `/mcp` to this base. A REST request such as `/projects` does not. Use the environment associated with your authorization flow; a Dev token and Dev project are not production credentials or data.

## 1. Confirm access and choose a project

Provide `IQRUSH_API_BASE` and `IQRUSH_ACCESS_TOKEN` through your application's secure configuration. Then run:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${IQRUSH_ACCESS_TOKEN}" \
  --header "Accept: application/json" \
  "${IQRUSH_API_BASE%/}/projects"
```

Expected response fields include `projects` and `count`. Select the intended project by name and workspace, then set `IQRUSH_PROJECT_ID` to its returned ID.

A successful empty list means no projects were returned for this account. An HTTP 401 means authorization failed. Follow [errors and recovery](/developers/guides/13-errors) for either case before continuing.

## 2. Choose a ready run

With `IQRUSH_PROJECT_ID` set, request the project’s runs:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${IQRUSH_ACCESS_TOKEN}" \
  "${IQRUSH_API_BASE%/}/projects/${IQRUSH_PROJECT_ID}/runs"
```

Select a run with `status: "COMPLETED"` and `data_ready: true`. The example below groups by platform, so also check `cold_path_ready` when supplied. Set `IQRUSH_RUN_ID` to the chosen run’s ID. Keep its `completed_at` date with the report.

## 3. Read a measurement

This request reads owned-domain coverage for each platform:

```bash theme={null}
curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer ${IQRUSH_ACCESS_TOKEN}" \
  --data-urlencode 'metric=coverage' \
  --data-urlencode 'aggregation_level=domain' \
  --data-urlencode 'subject={"kind":"owned"}' \
  --data-urlencode 'group_by=["platform"]' \
  "${IQRUSH_API_BASE%/}/projects/${IQRUSH_PROJECT_ID}/runs/${IQRUSH_RUN_ID}/citation-score"
```

Complex HTTP query parameters are JSON-encoded strings. Let your HTTP library encode query values; do not join unescaped JSON into a URL.

Read `data.rows`, each row’s `estimate`, and `data.filters_applied.warnings`. This confirms a metric read; it does not by itself establish decision-grade quality. The starter below also requests stability before producing its report.

## 4. Generate and review the report

[`http_report.py`](/examples/http_report.py) uses Python's standard library. [`http_report.mjs`](/examples/http_report.mjs) provides the equivalent JavaScript workflow with Node.js built-in libraries. With the same environment variables, it selects the latest completed, ready run unless you supply `IQRUSH_RUN_ID`, checks stability, and produces a small JSON report. It makes read requests only. It requires your own authorized credential and has not been authenticated to production as part of this documentation review.

Continue at [the report starter’s connection step](/developers/guides/24-report-starter) with the same base, access token, project ID, and selected run ID. If you have already discovered the IDs, proceed directly to its report-generation step.

HTTP and MCP defaults sometimes differ. Set `metric` and `aggregation_level` explicitly when matching a report across interfaces. See [HTTP reference](/developers/guides/20-http-reference).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.