Code examples

Starter snippets for calling the KiTbetter Partner API in commonly used languages.

Create an album ingest (`POST /ddex/ingests`)

Create a KiTalbum by passing a presigned URL to your DDEX ERN 3.8.2 XML. The ingest response can take up to 30 seconds, so set your client timeout to at least 30 seconds.

\=== "cURL"

```bash
curl -X POST "https://api.kitbetter.com/partner/v1/ddex/ingests" \
  -H "X-API-Key: $KIT_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 35 \
  -d '{
    "releaseId": "DIST-2026-00123",
    "xmlUrl": "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600"
  }'
```

\=== "Python"

```python
import os
import requests

BASE_URL = "https://api.kitbetter.com/partner/v1"

response = requests.post(
    f"{BASE_URL}/ddex/ingests",
    headers={"X-API-Key": os.environ["KIT_API_KEY"]},
    json={
        "releaseId": "DIST-2026-00123",
        "xmlUrl": "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600",
    },
    timeout=35,  # the ingest response can take up to 30s
)
response.raise_for_status()
ingest = response.json()
print(ingest["ingestId"], ingest["status"])
```

\=== "JavaScript"

```javascript
const BASE_URL = "https://api.kitbetter.com/partner/v1";

const response = await fetch(`${BASE_URL}/ddex/ingests`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.KIT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    releaseId: "DIST-2026-00123",
    xmlUrl: "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600",
  }),
  signal: AbortSignal.timeout(35_000), // the ingest response can take up to 30s
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}
const ingest = await response.json();
console.log(ingest.ingestId, ingest.status);
```

\=== "Go"

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "time"
)

func main() {
    payload, _ := json.Marshal(map[string]string{
        "releaseId": "DIST-2026-00123",
        "xmlUrl":    "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600",
    })

    req, _ := http.NewRequest("POST", "https://api.kitbetter.com/partner/v1/ddex/ingests", bytes.NewBuffer(payload))
    req.Header.Set("X-API-Key", os.Getenv("KIT_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{Timeout: 35 * time.Second} // the ingest response can take up to 30s
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var ingest map[string]any
    json.NewDecoder(resp.Body).Decode(&ingest)
    fmt.Println(ingest["ingestId"], ingest["status"])
}
```

\=== "Java"

```java
// Java 11+ (java.net.http)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class CreateIngest {
    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "releaseId": "DIST-2026-00123",
              "xmlUrl": "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600"
            }""";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.kitbetter.com/partner/v1/ddex/ingests"))
                .header("X-API-Key", System.getenv("KIT_API_KEY"))
                .header("Content-Type", "application/json")
                .timeout(Duration.ofSeconds(35)) // the ingest response can take up to 30s
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
```

\=== "Kotlin"

```kotlin
// JDK 11+ (java.net.http)
import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.time.Duration

fun main() {
    val payload = """
        {
          "releaseId": "DIST-2026-00123",
          "xmlUrl": "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600"
        }
    """.trimIndent()

    val client = HttpClient.newHttpClient()
    val request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.kitbetter.com/partner/v1/ddex/ingests"))
        .header("X-API-Key", System.getenv("KIT_API_KEY"))
        .header("Content-Type", "application/json")
        .timeout(Duration.ofSeconds(35)) // the ingest response can take up to 30s
        .POST(HttpRequest.BodyPublishers.ofString(payload))
        .build()

    val response = client.send(request, HttpResponse.BodyHandlers.ofString())
    println("${response.statusCode()} ${response.body()}")
}
```

\=== "C#"

```csharp
using System.Net.Http.Json;

var client = new HttpClient { Timeout = TimeSpan.FromSeconds(35) }; // the ingest response can take up to 30s
client.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("KIT_API_KEY"));

var response = await client.PostAsJsonAsync(
    "https://api.kitbetter.com/partner/v1/ddex/ingests",
    new
    {
        releaseId = "DIST-2026-00123",
        xmlUrl = "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600",
    });

response.EnsureSuccessStatusCode();
var ingest = await response.Content.ReadFromJsonAsync<Dictionary<string, object>>();
Console.WriteLine($"{ingest["ingestId"]} {ingest["status"]}");
```

\=== "PHP"

```php
<?php
$payload = json_encode([
    "releaseId" => "DIST-2026-00123",
    "xmlUrl" => "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600",
]);

$ch = curl_init("https://api.kitbetter.com/partner/v1/ddex/ingests");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: " . getenv("KIT_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 35, // the ingest response can take up to 30s
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$ingest = json_decode($body, true);
echo $ingest["ingestId"] . " " . $ingest["status"];
```

\=== "Ruby"

```ruby
require "json"
require "net/http"

uri = URI("https://api.kitbetter.com/partner/v1/ddex/ingests")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.read_timeout = 35 # the ingest response can take up to 30s

request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV["KIT_API_KEY"]
request["Content-Type"] = "application/json"
request.body = {
  releaseId: "DIST-2026-00123",
  xmlUrl: "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600"
}.to_json

response = http.request(request)
ingest = JSON.parse(response.body)
puts "#{ingest["ingestId"]} #{ingest["status"]}"
```

\=== "Rust"

```rust
// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }, serde_json = "1"
use std::{env, time::Duration};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::blocking::Client::builder()
        .timeout(Duration::from_secs(35)) // the ingest response can take up to 30s
        .build()?;

    let ingest: serde_json::Value = client
        .post("https://api.kitbetter.com/partner/v1/ddex/ingests")
        .header("X-API-Key", env::var("KIT_API_KEY")?)
        .json(&serde_json::json!({
            "releaseId": "DIST-2026-00123",
            "xmlUrl": "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600"
        }))
        .send()?
        .error_for_status()?
        .json()?;

    println!("{} {}", ingest["ingestId"], ingest["status"]);
    Ok(())
}
```

\=== "C++"

```cpp
// Uses cpr as the HTTP client (vcpkg install cpr) — libcurl directly works too
#include <cpr/cpr.h>
#include <cstdlib>
#include <iostream>

int main() {
    cpr::Response response = cpr::Post(
        cpr::Url{"https://api.kitbetter.com/partner/v1/ddex/ingests"},
        cpr::Header{{"X-API-Key", std::getenv("KIT_API_KEY")},
                    {"Content-Type", "application/json"}},
        cpr::Body{R"({
          "releaseId": "DIST-2026-00123",
          "xmlUrl": "https://your-bucket.s3.amazonaws.com/ern/abc.xml?X-Amz-Expires=3600"
        })"},
        cpr::Timeout{35'000}); // the ingest response can take up to 30s

    std::cout << response.status_code << " " << response.text << std::endl;
    return 0;
}
```

Requests with error handling

Two responses deserve special handling — 409 (duplicate ingest) carries details of the existing ingest in error.details, so you can treat it as a success if it is a retry after a timeout, while 422 (XML processing failed) means no ingest was created, so fix the cause and resend. Logging error.requestId from the response makes it much faster to trace the issue when you contact us.