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

# Usage Examples

> Code examples and common use cases for the Devin API

This page provides code examples for common API use cases. All examples use environment variables for credentials — set them once and every example is copy-paste ready. For full request/response schemas, refer to each endpoint's API reference page.

## Setup

Set these environment variables before running any example:

```bash theme={null}
# Required: your service user API key (starts with cog_)
export DEVIN_API_KEY="cog_your_key_here"

# Required: your organization ID (shown at the top of Settings → Devin API)
export DEVIN_ORG_ID="your_org_id"
```

<Tip>
  Find your organization ID at the top of the **Settings → Devin API** page.
</Tip>

## curl Examples

These examples work directly in your terminal after setting the environment variables above.

<AccordionGroup>
  <Accordion title="Create a session">
    ```bash theme={null}
    curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
      -H "Authorization: Bearer $DEVIN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"prompt": "Create a Python script that analyzes CSV data"}'
    ```
  </Accordion>

  <Accordion title="List sessions">
    ```bash theme={null}
    curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
      -H "Authorization: Bearer $DEVIN_API_KEY"
    ```
  </Accordion>

  <Accordion title="Send a message to a session">
    ```bash theme={null}
    export SESSION_ID="your_session_id"

    curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SESSION_ID/messages" \
      -H "Authorization: Bearer $DEVIN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"message": "Please also add unit tests"}'
    ```
  </Accordion>

  <Accordion title="Create a knowledge note">
    ```bash theme={null}
    curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes" \
      -H "Authorization: Bearer $DEVIN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Coding standards",
        "trigger": "When writing code in this repo",
        "body": "Use TypeScript strict mode. Follow the existing code style."
      }'
    ```
  </Accordion>

  <Accordion title="List enterprise organizations">
    ```bash theme={null}
    curl "https://api.devin.ai/v3/enterprise/organizations" \
      -H "Authorization: Bearer $DEVIN_API_KEY"
    ```
  </Accordion>

  <Accordion title="Get consumption data">
    ```bash theme={null}
    # Uses Unix timestamps — example: Jan 1 to Jan 31, 2025
    curl "https://api.devin.ai/v3/enterprise/consumption/daily?time_after=1735689600&time_before=1738368000" \
      -H "Authorization: Bearer $DEVIN_API_KEY"
    ```
  </Accordion>
</AccordionGroup>

## Python Examples

<AccordionGroup>
  <Accordion title="Create a session">
    ```python theme={null}
    import os
    import requests

    API_KEY = os.environ["DEVIN_API_KEY"]
    ORG_ID = os.environ["DEVIN_ORG_ID"]
    BASE_URL = "https://api.devin.ai/v3"

    response = requests.post(
        f"{BASE_URL}/organizations/{ORG_ID}/sessions",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "prompt": "Create a Python script that analyzes CSV data"
        }
    )
    response.raise_for_status()

    session = response.json()
    print(f"Session created: {session['session_id']}")
    print(f"URL: {session['url']}")
    ```
  </Accordion>

  <Accordion title="Poll session status">
    ```python theme={null}
    import os
    import time
    import requests

    API_KEY = os.environ["DEVIN_API_KEY"]
    ORG_ID = os.environ["DEVIN_ORG_ID"]
    BASE_URL = "https://api.devin.ai/v3"
    SESSION_ID = os.environ.get("SESSION_ID", "your_session_id")

    while True:
        response = requests.get(
            f"{BASE_URL}/organizations/{ORG_ID}/sessions/{SESSION_ID}",
            headers={"Authorization": f"Bearer {API_KEY}"}
        )
        response.raise_for_status()
        session = response.json()

        status = session["status"]
        print(f"Status: {status}")

        # Terminal statuses: "exit" (completed), "error", "suspended"
        if status in ("exit", "error", "suspended"):
            break

        time.sleep(10)
    ```
  </Accordion>

  <Accordion title="Multi-org workflow (enterprise)">
    Automate across multiple organizations:

    ```python theme={null}
    import os
    import requests

    API_KEY = os.environ["DEVIN_API_KEY"]
    BASE_URL = "https://api.devin.ai/v3"

    # Get all organizations
    orgs_response = requests.get(
        f"{BASE_URL}/enterprise/organizations",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    orgs_response.raise_for_status()
    organizations = orgs_response.json()["items"]

    # Create a session in each organization
    for org in organizations:
        session_response = requests.post(
            f"{BASE_URL}/organizations/{org['org_id']}/sessions",
            headers={
                "Authorization": f"Bearer {API_KEY}",
                "Content-Type": "application/json"
            },
            json={
                "prompt": f"Run daily health check for {org['name']}"
            }
        )

        if session_response.ok:
            session = session_response.json()
            print(f"Created session for {org['name']}: {session['session_id']}")
        else:
            print(f"Failed for {org['name']}: {session_response.status_code}")
    ```
  </Accordion>

  <Accordion title="Paginated audit log retrieval (enterprise)">
    ```python theme={null}
    import os
    import requests
    from datetime import datetime, timedelta, timezone

    API_KEY = os.environ["DEVIN_API_KEY"]
    BASE_URL = "https://api.devin.ai/v3"

    # Last 7 days as Unix timestamps
    now = datetime.now(timezone.utc)
    seven_days_ago = now - timedelta(days=7)

    params = {
        "time_after": int(seven_days_ago.timestamp()),
        "time_before": int(now.timestamp()),
        "first": 100,
    }

    all_logs = []
    while True:
        response = requests.get(
            f"{BASE_URL}/enterprise/audit-logs",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params=params,
        )
        response.raise_for_status()
        data = response.json()

        all_logs.extend(data["items"])
        print(f"Fetched {len(data['items'])} logs (total: {len(all_logs)})")

        if not data.get("has_next_page"):
            break
        params["after"] = data["end_cursor"]

    for log in all_logs:
        ts = datetime.fromtimestamp(log["created_at"], tz=timezone.utc).isoformat()
        actor = log.get("service_user_id") or log.get("user_id") or "system"
        print(f"{ts} - {log['action']} (actor={actor})")
    ```
  </Accordion>

  <Accordion title="Error handling">
    ```python theme={null}
    import os
    import requests

    API_KEY = os.environ["DEVIN_API_KEY"]
    ORG_ID = os.environ["DEVIN_ORG_ID"]
    BASE_URL = "https://api.devin.ai/v3"

    try:
        response = requests.get(
            f"{BASE_URL}/organizations/{ORG_ID}/sessions",
            headers={"Authorization": f"Bearer {API_KEY}"}
        )
        response.raise_for_status()
        data = response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            print("Invalid or expired API key")
        elif e.response.status_code == 403:
            print("Service user lacks required permission")
        elif e.response.status_code == 429:
            print("Rate limit exceeded — wait and retry")
        else:
            print(f"API error: {e.response.status_code} {e.response.text}")
    ```
  </Accordion>
</AccordionGroup>

## Support

<Card title="Need Help?">
  For questions about the API or to report issues, email [support@cognition.ai](mailto:support@cognition.ai)
</Card>