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

# API quickstart

> Score products programmatically using the Dacard.ai API.

<Note>
  Authenticate with a Bearer token, drop a URL, get a scored product back. Full endpoint reference at [API Reference](/api-reference/scoring/score-a-url). Rate limits and credit costs depend on your plan.
</Note>

# API quickstart

Our API lets you score products, retrieve results, and manage your account programmatically. This page walks you through auth, your first call, and key concepts.

## Authentication

All authenticated endpoints accept a **Bearer token** in the `Authorization` header. You can obtain tokens in two ways:

<Tabs>
  <Tab title="API Key">
    Generate an API key under **Settings > API Keys** in the platform. API keys are long-lived and suitable for server-to-server integrations.

    ```bash theme={null}
    curl -H "Authorization: Bearer dac_your_api_key_here" \
      https://app.dacard.ai/api/scores
    ```
  </Tab>

  <Tab title="Session Token">
    If you are building a client-side integration, use Clerk's `getToken()` method to obtain a short-lived JWT.

    ```typescript theme={null}
    const token = await clerk.session?.getToken();
    const res = await fetch('https://app.dacard.ai/api/scores', {
      headers: { Authorization: `Bearer ${token}` },
    });
    ```
  </Tab>
</Tabs>

<Warning>
  Never expose API keys in client-side code or public repositories. Use environment variables for all credentials.
</Warning>

## Score a product

Send a `POST` request to `/api/score` with the product URL:

```bash theme={null}
curl -X POST https://app.dacard.ai/api/score \
  -H "Authorization: Bearer dac_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://linear.app",
    "context": "Linear is a project management tool for software teams"
  }'
```

The response includes the full scoring result:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://linear.app",
  "companyName": "Linear",
  "totalScore": 78,
  "stageName": "Leading",
  "dimensions": [
    {
      "dimensionId": "market_intelligence",
      "dimensionName": "Market Intelligence",
      "score": 4,
      "stageName": "Compounding",
      "evidence": "...",
      "confidence": "high",
      "reasoning": "..."
    }
  ],
  "strengths": ["delivery_velocity", "experience_design", "architecture_systems"],
  "gaps": ["cost_token_economics", "data_strategy_flywheel", "pricing_packaging"],
  "createdAt": "2026-04-07T12:00:00.000Z"
}
```

<Tip>
  The optional `context` field helps the scoring engine understand the product better, especially for products with minimal public-facing content. Include a brief description of what the product does and who it serves.
</Tip>

## Retrieve results

Scoring results are accessible by ID. This endpoint is public (no auth required), supporting shareable result URLs.

```bash theme={null}
curl https://app.dacard.ai/api/score/550e8400-e29b-41d4-a716-446655440000
```

To list your score history:

```bash theme={null}
curl -H "Authorization: Bearer dac_your_api_key_here" \
  https://app.dacard.ai/api/scores
```

## Product Assessment

Score a product using the Product Assessment framework:

```bash theme={null}
curl -X POST https://app.dacard.ai/api/score/product \
  -H "Authorization: Bearer dac_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://linear.app",
    "context": "Linear is a project management tool with assistive features"
  }'
```

## Lifecycle assessment

Retrieve lifecycle stage definitions (public, no auth):

```bash theme={null}
curl https://app.dacard.ai/api/lifecycle/stages
```

Submit a lifecycle self-assessment:

```bash theme={null}
curl -X POST https://app.dacard.ai/api/lifecycle/assessment \
  -H "Authorization: Bearer dac_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "answers": {
      "task_define_problem": "completed",
      "task_user_research": "in_progress",
      "task_competitive_analysis": "not_started"
    }
  }'
```

## Rate limits and credits

| Resource     | Limit                                 |
| ------------ | ------------------------------------- |
| URL score    | 10 credits per score                  |
| Chat message | 1 credit per message                  |
| API call     | 0.1 credits per call                  |
| Rate limit   | Plan-dependent (see Settings > Usage) |

Credits reset monthly. Monitor your usage with the usage endpoint:

```bash theme={null}
curl -H "Authorization: Bearer dac_your_api_key_here" \
  https://app.dacard.ai/api/usage
```

### Error codes

| Code              | Status | Description                              |
| ----------------- | ------ | ---------------------------------------- |
| `AUTH_REQUIRED`   | 401    | Missing or invalid authentication        |
| `FORBIDDEN`       | 403    | Insufficient permissions                 |
| `NOT_FOUND`       | 404    | Resource not found                       |
| `INVALID_URL`     | 400    | URL is malformed or unreachable          |
| `CRAWL_FAILED`    | 400    | Failed to crawl the target URL           |
| `QUOTA_EXCEEDED`  | 429    | Monthly credit limit reached             |
| `ANON_RATE_LIMIT` | 429    | Anonymous rate limit (1 per IP per hour) |

## Health check

Verify the platform is operational:

```bash theme={null}
curl https://app.dacard.ai/api/health
```

Returns component-level status for database, auth, billing, scoring, and environment checks.

## Next steps

<CardGroup cols={2}>
  <Card title="Full API Reference" icon="book" href="/api-reference/scoring/score-a-url">
    Complete endpoint documentation with request/response schemas.
  </Card>

  <Card title="SDKs" icon="code" href="/sdks">
    Client libraries for TypeScript and other languages.
  </Card>
</CardGroup>