Batch Operations

curl --request POST \
  --url https://api.debtstack.ai/v1/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "operations": [
    {
      "primitive": "<string>",
      "params": {}
    }
  ]
}
'

import requests

url = "https://api.debtstack.ai/v1/batch"

payload = { "operations": [
        {
            "primitive": "<string>",
            "params": {}
        }
    ] }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({operations: [{primitive: '<string>', params: {}}]})
};

fetch('https://api.debtstack.ai/v1/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.debtstack.ai/v1/batch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'operations' => [
        [
                'primitive' => '<string>',
                'params' => [
                                
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.debtstack.ai/v1/batch"

	payload := strings.NewReader("{\n  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.debtstack.ai/v1/batch")
  .header("Content-Type", "application/json")
  .body("{\n  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.debtstack.ai/v1/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "primitive": "<string>",
      "status": "<string>",
      "data": "<any>",
      "error": {}
    }
  ],
  "meta": {
    "total_operations": 123,
    "successful": 123,
    "failed": 123,
    "duration_ms": 123
  }
}

POST

batch

Batch Operations

curl --request POST \
  --url https://api.debtstack.ai/v1/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "operations": [
    {
      "primitive": "<string>",
      "params": {}
    }
  ]
}
'

import requests

url = "https://api.debtstack.ai/v1/batch"

payload = { "operations": [
        {
            "primitive": "<string>",
            "params": {}
        }
    ] }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({operations: [{primitive: '<string>', params: {}}]})
};

fetch('https://api.debtstack.ai/v1/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.debtstack.ai/v1/batch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'operations' => [
        [
                'primitive' => '<string>',
                'params' => [
                                
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.debtstack.ai/v1/batch"

	payload := strings.NewReader("{\n  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.debtstack.ai/v1/batch")
  .header("Content-Type", "application/json")
  .body("{\n  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.debtstack.ai/v1/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "primitive": "<string>",
      "status": "<string>",
      "data": "<any>",
      "error": {}
    }
  ],
  "meta": {
    "total_operations": 123,
    "successful": 123,
    "failed": 123,
    "duration_ms": 123
  }
}

Overview

Execute multiple primitive operations in a single request. Operations run in parallel for optimal performance. Useful for reducing round-trips when you need data from multiple endpoints.

Request

array

required

Array of operations to execute (max 10).

Show properties

string

required

The primitive to execute. See supported primitives below.

object

required

Parameters for the primitive (same as query params for GET endpoints).

Supported Primitives

Primitive	Maps To
`search.companies`	`GET /v1/companies`
`search.bonds`	`GET /v1/bonds`
`resolve.bond`	`GET /v1/bonds/resolve`
`search.pricing`	`GET /v1/pricing`
`traverse.entities`	`POST /v1/entities/traverse`
`search.documents`	`GET /v1/documents/search`

Response

array

Array of results, one per operation.

Show properties

string

The primitive that was executed.

string

success or error

any

The result data (same as individual endpoint).

object

Error details if status is error.

object

Show properties

integer

Number of operations requested.

integer

Number of successful operations.

integer

Number of failed operations.

integer

Total execution time in milliseconds.

Examples

Multiple Data Types

Get company metrics and bonds in one call:

curl -X POST "https://api.debtstack.ai/v1/batch" \
  -H "X-API-Key: ds_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "primitive": "search.companies",
        "params": {
          "ticker": "RIG",
          "fields": "ticker,name,net_leverage_ratio,total_debt"
        }
      },
      {
        "primitive": "search.bonds",
        "params": {
          "ticker": "RIG",
          "has_pricing": true,
          "fields": "name,cusip,maturity_date,pricing"
        }
      }
    ]
  }'

import requests

response = requests.post(
    "https://api.debtstack.ai/v1/batch",
    headers={
        "X-API-Key": "ds_xxxxx",
        "Content-Type": "application/json"
    },
    json={
        "operations": [
            {
                "primitive": "search.companies",
                "params": {
                    "ticker": "RIG",
                    "fields": "ticker,name,net_leverage_ratio,total_debt"
                }
            },
            {
                "primitive": "search.bonds",
                "params": {
                    "ticker": "RIG",
                    "has_pricing": True,
                    "fields": "name,cusip,maturity_date,pricing"
                }
            }
        ]
    }
)

results = response.json()["results"]
company = results[0]["data"][0]
bonds = results[1]["data"]

print(f"{company['name']}: {company['net_leverage_ratio']}x leverage")
print(f"Bonds with pricing: {len(bonds)}")

Response

{
  "results": [
    {
      "primitive": "search.companies",
      "status": "success",
      "data": [
        {
          "ticker": "RIG",
          "name": "Transocean Ltd.",
          "net_leverage_ratio": 4.2,
          "total_debt": 750000000000
        }
      ],
      "meta": {"total": 1}
    },
    {
      "primitive": "search.bonds",
      "status": "success",
      "data": [
        {
          "name": "8.00% Senior Notes due 2027",
          "cusip": "893830AK8",
          "maturity_date": "2027-02-01",
          "pricing": {
            "last_price": 94.25,
            "ytm": 9.42,
            "spread": 512
          }
        }
      ],
      "meta": {"total": 6}
    }
  ],
  "meta": {
    "total_operations": 2,
    "successful": 2,
    "failed": 0,
    "duration_ms": 145
  }
}

Compare Multiple Companies

response = requests.post(
    f"{BASE_URL}/batch",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "operations": [
            {
                "primitive": "search.companies",
                "params": {
                    "ticker": "RIG",
                    "fields": "ticker,name,net_leverage_ratio"
                }
            },
            {
                "primitive": "search.companies",
                "params": {
                    "ticker": "VAL",
                    "fields": "ticker,name,net_leverage_ratio"
                }
            },
            {
                "primitive": "search.companies",
                "params": {
                    "ticker": "DO",
                    "fields": "ticker,name,net_leverage_ratio"
                }
            }
        ]
    }
)

# Compare leverage across drilling companies
for result in response.json()["results"]:
    if result["status"] == "success" and result["data"]:
        company = result["data"][0]
        print(f"{company['ticker']}: {company['net_leverage_ratio']}x")

Mixed Primitives

response = requests.post(
    f"{BASE_URL}/batch",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "operations": [
            # Get company info
            {
                "primitive": "search.companies",
                "params": {"ticker": "CHTR", "fields": "ticker,name,total_debt"}
            },
            # Resolve a bond
            {
                "primitive": "resolve.bond",
                "params": {"q": "CHTR 5% 2028"}
            },
            # Search for covenant language
            {
                "primitive": "search.documents",
                "params": {
                    "q": "leverage covenant",
                    "ticker": "CHTR",
                    "section_type": "credit_agreement",
                    "limit": 3
                }
            }
        ]
    }
)

Error Handling

If one operation fails, others still execute:

{
  "results": [
    {
      "primitive": "search.companies",
      "status": "success",
      "data": [...]
    },
    {
      "primitive": "resolve.bond",
      "status": "error",
      "error": {
        "code": "NOT_FOUND",
        "message": "No matching bonds found for query 'XYZ 5% 2025'"
      }
    }
  ],
  "meta": {
    "total_operations": 2,
    "successful": 1,
    "failed": 1
  }
}

Check status for each operation:

for result in response.json()["results"]:
    if result["status"] == "success":
        print(f"{result['primitive']}: {len(result.get('data', []))} results")
    else:
        print(f"{result['primitive']}: ERROR - {result['error']['message']}")

Limits

Maximum 10 operations per batch
Each operation counts toward rate limits
Credit cost is sum of individual operations

Use Cases

Complete Company Profile

def get_company_profile(ticker):
    """Get complete company data in one call."""
    response = requests.post(
        f"{BASE_URL}/batch",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={
            "operations": [
                {"primitive": "search.companies", "params": {"ticker": ticker}},
                {"primitive": "search.bonds", "params": {"ticker": ticker}},
                {"primitive": "search.pricing", "params": {"ticker": ticker}}
            ]
        }
    )

    results = response.json()["results"]
    return {
        "company": results[0]["data"][0] if results[0]["data"] else None,
        "bonds": results[1]["data"],
        "pricing": results[2]["data"]
    }

Portfolio Overview

def portfolio_overview(tickers):
    """Get key metrics for multiple companies."""
    operations = [
        {
            "primitive": "search.companies",
            "params": {
                "ticker": ticker,
                "fields": "ticker,name,net_leverage_ratio,total_debt"
            }
        }
        for ticker in tickers
    ]

    response = requests.post(
        f"{BASE_URL}/batch",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={"operations": operations[:10]}  # Max 10
    )

    return [
        r["data"][0] for r in response.json()["results"]
        if r["status"] == "success" and r["data"]
    ]

Overview

Companies

Bonds

Financials

Collateral

Entities

Documents

Covenants

Ratings

Market Data

Batch

Batch Operations

Overview

Request

Supported Primitives

Response

Examples

Multiple Data Types

Response

Compare Multiple Companies

Mixed Primitives

Error Handling

Limits

Use Cases

Complete Company Profile

Portfolio Overview

​Overview

​Request

​Supported Primitives

​Response

​Examples

​Multiple Data Types

​Response

​Compare Multiple Companies

​Mixed Primitives

​Error Handling

​Limits

​Use Cases

​Complete Company Profile

​Portfolio Overview

Overview

Request

Supported Primitives

Response

Examples

Multiple Data Types

Response

Compare Multiple Companies

Mixed Primitives

Error Handling

Limits

Use Cases

Complete Company Profile

Portfolio Overview