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

# Overview

The Foveus API lets SDKs and services send telemetry to your workspace and retrieve observability data from the dashboard.

Most teams do not need to call the API directly at first.

Start with the .NET SDK:

```csharp theme={null}
builder.Services.AddFoveus("fov_test_...");
app.UseFoveus();
```

The SDK handles authentication, batching, retries, capture, redaction, and ingestion.

## When to use the API directly

Use the API directly when you need to:

* build a custom SDK or integration
* ingest telemetry from a platform Foveus does not support yet
* automate workspace setup
* query executions programmatically
* connect Foveus data to internal tools
* build custom operational workflows

For most .NET services, use the SDK instead.

## Authentication

Foveus API requests use API keys.

Test keys are created automatically during onboarding.

```text theme={null}
fov_test_...
```

Live keys are created manually from Settings.

```text theme={null}
fov_live_...
```

Send the key from your backend service only.

<Warning>
  Do not expose Foveus API keys in frontend JavaScript, mobile apps, public repositories, logs, screenshots, or client-side applications.
</Warning>

## Modes

Foveus separates telemetry into two modes.

| Mode   | Use for                                                |
| ------ | ------------------------------------------------------ |
| `test` | Local development, sandbox testing, QA, and onboarding |
| `live` | Production telemetry                                   |

Foveus defaults to Test mode.

Set `Mode` to `live` only when sending production telemetry with a live key.

## Main API areas

The Foveus API is organized around telemetry and investigation workflows.

| Area       | Purpose                                                      |
| ---------- | ------------------------------------------------------------ |
| Ingestion  | Send executions, logs, metrics, context, and issue evidence. |
| Executions | Query execution records and open execution details.          |
| Issues     | Query grouped failure patterns and linked executions.        |
| Logs       | Query logs correlated to executions.                         |
| Metrics    | Query aggregated service and system metrics.                 |
| Workspace  | Manage workspace-level configuration and settings.           |
| API keys   | Manage live API keys and permissions.                        |

## Ingestion API

The ingestion API receives telemetry from SDKs and integrations.

It can include:

* execution metadata
* request context
* response context
* logs
* metrics
* exceptions
* outcome evidence
* custom context

For most services, the SDK sends ingestion data automatically.

## Executions API

The Executions API powers the Executions page.

It can be used to query executions by:

* service
* status
* method
* endpoint
* execution ID
* trace ID
* issue ID
* duration
* time range
* indexed context fields

Example query shape:

```http theme={null}
GET /api/executions?mode=test&serviceName=orders-api&page=1&pageSize=25
```

Context search uses indexed context fields:

```http theme={null}
GET /api/executions?mode=test&serviceName=orders-api&context.customerId=cus_12345&includeMatchedContext=true&page=1&pageSize=25
```

In the dashboard search bar, the same search is written as:

```text theme={null}
service:orders-api context:customerId="cus_12345"
```

## Issues API

The Issues API powers issue triage views.

Issues represent grouped failure patterns.

An issue can include:

* title
* status
* service
* failure type
* hypothesis
* suggested fix
* common factors
* occurrence counts
* linked executions
* lifecycle timestamps
* assignment
* comments and activity

Use issues when you want to understand repeated or meaningful failure patterns.

## Logs API

The Logs API powers log exploration and execution-linked logs.

Logs are most useful when correlated to executions.

Use linked logs to inspect log lines for one request, job, or operation instead of searching through unrelated streams.

## Metrics API

The Metrics API powers dashboard and service metrics.

Metrics can include:

* request volume
* failure rate
* latency
* service health
* throughput
* system trends
* aggregated telemetry

Use metrics for trends and overview.

Use executions for exact investigation.

## Context search API

Execution Context Search lets you find executions by indexed business context.

Example dashboard query:

```text theme={null}
service:orders-api context:orderStatus.value=1
```

Equivalent API shape:

```http theme={null}
GET /api/executions?mode=test&serviceName=orders-api&context.orderStatus.value=1&includeMatchedContext=true&page=1&pageSize=25
```

String values should be quoted in the dashboard query language:

```text theme={null}
service:orders-api context:customerId="cus_12345"
```

When calling the API directly, URL-encode values where needed.

## Pagination

List endpoints use pagination.

Common parameters include:

| Parameter  | Description               |
| ---------- | ------------------------- |
| `page`     | Page number.              |
| `pageSize` | Number of items per page. |

Example:

```http theme={null}
GET /api/executions?mode=test&serviceName=orders-api&page=1&pageSize=25
```

## Error responses

Foveus APIs return structured errors.

Common error types may include:

| Error                     | Meaning                                               |
| ------------------------- | ----------------------------------------------------- |
| `UNAUTHORIZED`            | The API key or user session is invalid.               |
| `FORBIDDEN`               | The caller does not have permission.                  |
| `VALIDATION_ERROR`        | The request contains invalid fields.                  |
| `CONTEXT_KEY_NOT_ALLOWED` | The context key is not enabled or allowed for search. |
| `CONTEXT_QUERY_TOO_BROAD` | The context search is too broad without enough scope. |

Error names may evolve during private beta.

## Rate limits and guardrails

Foveus applies guardrails to protect workspace performance and ingestion reliability.

These can include:

* API key rate limits
* request size limits
* context indexing limits
* maximum page size
* maximum context keys per request
* maximum values per key
* time-window limits for broad context searches

These limits help keep searches predictable and safe.

## Private beta note

The public API reference is still evolving during private beta.

Use the SDK where possible.

If you need direct API access, confirm the current endpoint contract with the Foveus team before building production workflows against it.

## What to do next

* Install the .NET SDK: [Install the .NET SDK](/get-started/install-dotnet-sdk)
* Configure the SDK: [SDK configuration](/sdk/configuration)
* Learn about executions: [Executions](/concepts/executions)
* Learn about context search: [Execution Context Search](/concepts/execution-context-search)
* Review API key safety: [API keys](/security/api-keys)