> ## 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](https://docs.dacard.ai/api-reference/scoring/score-a-url.md).

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

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

**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}` },
});
```

> [!WARNING]
>
> Never expose API keys in client-side code or public repositories. Use environment variables for all credentials.

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

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

> **[Full API Reference](https://docs.dacard.ai/api-reference/scoring/score-a-url.md)**
>
> Complete endpoint documentation with request/response schemas.

> **[Connect integrations](https://docs.dacard.ai/knowledge-base/integrations.md)**
>
> Pull real operational signals into scoring via integrations.

> **[Webhooks reference](https://docs.dacard.ai/webhooks.md)**
>
> Stripe webhook events for billing lifecycle management.

> **[Agent Studio](https://docs.dacard.ai/knowledge-base/agent-studio.md)**
>
> Automate intelligence gathering with autonomous agents.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.