> ## 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](https://docs.dacard.ai/api-reference/scoring/score-a-url.md). Rate limits and credit costs depend on your plan.

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

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

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

> [!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:

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

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

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

> **[SDKs](https://docs.dacard.ai/sdks.md)**
>
> Client libraries for TypeScript and other languages.


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