How to Use the Company Endpoint in the Claude API: A Practical Guide

Introduction

When working with the Claude API at scale, managing your organization’s settings efficiently is crucial. The Company endpoint in the Claude API provides a centralized way to retrieve and update your organization’s information, billing details, and configuration preferences. Whether you’re a solo developer or part of a larger team, understanding this endpoint helps you automate administrative tasks and keep your Claude integration running smoothly.

In this guide, you’ll learn:

• What the Company endpoint is and when to use it
• How to authenticate and make requests
• Practical code examples in Python and TypeScript
• Best practices for managing your organization’s settings

Let’s dive in.

What Is the Company Endpoint?

The Company endpoint (/v1/organizations/company) allows you to interact with your organization’s profile within the Claude API ecosystem. It’s designed for tasks like:

• Retrieving your organization’s name, ID, and metadata
• Updating billing information or plan details
• Managing team member permissions (if applicable)
• Checking usage limits and quotas

This endpoint is particularly useful for:

• Team leads who need to monitor API usage across projects
• DevOps engineers automating infrastructure provisioning
• Solo developers managing multiple API keys under one organization

Prerequisites

Before using the Company endpoint, ensure you have:

• A Claude API account with an active organization
• An API key with appropriate permissions (admin or billing access)
• Basic familiarity with HTTP requests and JSON

Note: Your API key must have the organization:read or organization:write scope to access this endpoint. Check your API key settings in the Anthropic Console.

Authentication

All requests to the Company endpoint require authentication via the x-api-key header. Here’s how to set it up:

import requests
API_KEY = "your-api-key-here"
HEADERS = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}

const API_KEY = "your-api-key-here";
const headers = {
  "x-api-key": API_KEY,
  "Content-Type": "application/json"
};

Core Operations

1. Retrieve Company Information

To get your organization’s details, send a GET request to the Company endpoint:

import requests
url = "https://api.anthropic.com/v1/organizations/company"
response = requests.get(url, headers=HEADERS)
if response.status_code == 200:
    company_data = response.json()
    print(f"Organization: {company_data['name']}")
    print(f"ID: {company_data['id']}")
    print(f"Plan: {company_data['plan']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

const url = "https://api.anthropic.com/v1/organizations/company";
fetch(url, { method: "GET", headers })
  .then(response => response.json())
  .then(data => {
    console.log(Organization: ${data.name});
    console.log(ID: ${data.id});
    console.log(Plan: ${data.plan});
  })
  .catch(error => console.error("Error:", error));

Sample Response:

{
  "id": "org_abc123",
  "name": "My Awesome Team",
  "plan": "team",
  "created_at": "2024-01-15T10:30:00Z",
  "billing_email": "[email protected]",
  "usage_limit": 1000000
}

2. Update Company Settings

To update your organization’s settings (e.g., billing email or display name), use a PATCH request:

import requests
url = "https://api.anthropic.com/v1/organizations/company"
payload = {
    "name": "My Updated Team",
    "billing_email": "[email protected]"
}
response = requests.patch(url, json=payload, headers=HEADERS)
if response.status_code == 200:
    print("Company updated successfully")
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

const url = "https://api.anthropic.com/v1/organizations/company";
const payload = {
  name: "My Updated Team",
  billing_email: "[email protected]"
};
fetch(url, {
  method: "PATCH",
  headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log("Company updated:", data))
  .catch(error => console.error("Error:", error));

3. Check Usage and Limits

You can also retrieve your organization’s current usage statistics:

import requests
url = "https://api.anthropic.com/v1/organizations/company/usage"
response = requests.get(url, headers=HEADERS)
if response.status_code == 200:
    usage = response.json()
    print(f"Tokens used this month: {usage['tokens_used']}")
    print(f"Tokens remaining: {usage['tokens_remaining']}")
    print(f"API calls made: {usage['api_calls']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Best Practices

1. Cache Company Data

Company information rarely changes, so cache it locally to reduce API calls:

import time
class CompanyCache:
    def __init__(self, ttl=3600):
        self.data = None
        self.timestamp = 0
        self.ttl = ttl
    
    def get_company_info(self):
        if time.time() - self.timestamp > self.ttl:
            # Fetch fresh data
            response = requests.get(url, headers=HEADERS)
            if response.status_code == 200:
                self.data = response.json()
                self.timestamp = time.time()
        return self.data

2. Handle Errors Gracefully

Always implement proper error handling for network issues or permission errors:

try:
    response = requests.get(url, headers=HEADERS, timeout=10)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    if response.status_code == 403:
        print("Permission denied. Check your API key scopes.")
    elif response.status_code == 429:
        print("Rate limited. Retry after:", response.headers.get("Retry-After"))
    else:
        print(f"HTTP error: {e}")
except requests.exceptions.ConnectionError:
    print("Network error. Check your internet connection.")
except requests.exceptions.Timeout:
    print("Request timed out. Try again later.")

3. Use Environment Variables

Never hardcode your API key. Use environment variables instead:

import os
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.getenv("CLAUDE_API_KEY")

Common Use Cases

Automating Billing Updates

If you need to update billing information across multiple projects, you can script it:

import requests
projects = ["proj_1", "proj_2", "proj_3"]
for project_id in projects:
    url = f"https://api.anthropic.com/v1/organizations/company/projects/{project_id}"
    payload = {"billing_email": "[email protected]"}
    response = requests.patch(url, json=payload, headers=HEADERS)
    if response.status_code == 200:
        print(f"Updated billing for {project_id}")
    else:
        print(f"Failed for {project_id}: {response.text}")

Monitoring Usage Across Teams

Create a dashboard that polls the Company endpoint periodically:

import time
import json
def monitor_usage(interval=300):
    while True:
        response = requests.get(url + "/usage", headers=HEADERS)
        if response.status_code == 200:
            data = response.json()
            with open("usage_log.json", "a") as f:
                f.write(json.dumps(data) + "\n")
            print(f"Logged usage at {time.ctime()}")
        time.sleep(interval)

Troubleshooting

Conclusion

The Company endpoint is a powerful tool for managing your Claude API organization. By mastering its core operations—retrieving company info, updating settings, and monitoring usage—you can automate administrative workflows and keep your team’s integration running efficiently.

Remember to:

• Always authenticate with a properly scoped API key
• Cache data when possible to minimize API calls
• Implement robust error handling for production use

Key Takeaways

• The Company endpoint (/v1/organizations/company) lets you manage your organization’s profile, billing, and usage via the Claude API.
• Use GET requests to retrieve company info and PATCH requests to update settings like name or billing email.
• Always authenticate with an API key that has the organization:read or organization:write scope.
• Cache company data locally and implement error handling to build resilient integrations.
• Monitor usage regularly to avoid hitting rate limits and to track costs across your team.

Now go ahead and streamline your Claude API organization management!