> ## 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.

# Developer API quickstart

> Score products programmatically using the Dacard.ai API.

<Note>
  Authenticate with a Bearer token, drop a URL, get a scored product back. Wire it into CI/CD, internal tools, or customer-facing surfaces. Full reference at [API Reference](/api-reference/scoring/score-a-url).
</Note>

# Developer API quickstart

As a developer, you want to score products programmatically so you can wire maturity scoring into your CI/CD pipeline, internal tools, or customer-facing surfaces.

## Authentication

All authenticated endpoints accept a **Bearer token** in the `Authorization` header:

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

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

  <Tab title="Session Token (client-side)">
    Use Clerk's `getToken()` method for short-lived JWTs in client-side integrations.

    ```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 with all 27 dimensions:

```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 products with minimal public 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 URLs:

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

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 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     | Cost                 |
| ------------ | -------------------- |
| URL score    | 10 credits per score |
| Chat message | 1 credit per message |
| API call     | 0.1 credits per call |

Credits reset monthly. Monitor usage:

```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

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

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

## 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="Connect integrations" icon="plug" href="/knowledge-base/integrations">
    Pull real operational signals into scoring via integrations.
  </Card>

  <Card title="Webhooks reference" icon="bell" href="/webhooks">
    Stripe webhook events for billing lifecycle management.
  </Card>

  <Card title="Agent Studio" icon="wand-magic-sparkles" href="/knowledge-base/agent-studio">
    Automate intelligence gathering with autonomous agents.
  </Card>
</CardGroup>