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

# C++ example

> How to call our media API from C++ using CPR and nlohmann/json.

This is a usage example, not a published package. `cpp/` in the repo contains a single-header helper (`client.hpp`) that wraps CPR and nlohmann/json. Copy it into your project or pull it via CMake FetchContent — there is no package to install from a registry.

If you're building in C++, the API is straightforward HTTP with JSON. You can use any HTTP client you already have; the header is just a convenience wrapper.

## Pull into your CMake project

```cmake theme={null}
include(FetchContent)
FetchContent_Declare(
  sf_voice
  GIT_REPOSITORY https://github.com/icelab-research/raidzero
  GIT_TAG        main
  SOURCE_SUBDIR  cpp
)
FetchContent_MakeAvailable(sf_voice)

target_link_libraries(your_target PRIVATE sf_voice::sf_voice)
```

Or copy `cpp/include/sf_voice/client.hpp` directly. You need CPR and nlohmann/json on your include path either way.

## Create a client

```cpp theme={null}
#include <sf_voice/sf_voice.hpp>

sf_voice::SfVoiceMedia client(std::getenv("SF_VOICE_API_KEY"));
```

## Ingest

```cpp theme={null}
sf_voice::IngestRequest req;
req.source      = "url";
req.asset_id    = "call_001";
req.asset_class = "customer_acme";
req.url         = "https://storage.example.com/calls/001.mp3";
req.media_type  = "audio";

auto result = client.ingest(req).get();

if (!result.ok) {
    std::cerr << result.error.message << "\n";
    return;
}

auto task_id = result.value.task_id;
```

## Poll until ready

```cpp theme={null}
auto task = client.poll_task(task_id).get();

if (!task.ok) {
    std::cerr << task.error.message << "\n";
    return;
}

if (task.value.status == sf_voice::TaskStatus::Failed) {
    std::cerr << "indexing failed\n";
}
```

## Search

```cpp theme={null}
sf_voice::SearchRequest req;
req.query       = "customer asks about pricing";
req.asset_class = "customer_acme";
req.types       = {sf_voice::SearchType::Transcript};
req.threshold   = 0.7f;

auto result = client.search(req).get();

if (result.ok) {
    for (const auto& r : result.value.results) {
        std::cout << r.asset_id << " "
                  << r.start_ms.value_or(0) << "–"
                  << r.end_ms.value_or(0) << "ms\n";
    }
}
```

## Result type

All methods return `std::future<Result<T>>`. Check the `ok` field before use:

```cpp theme={null}
if (result.ok) {
    // result.value — the response
} else {
    // result.error.code, result.error.message, result.error.status
}
```


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