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

# POST /api/geo-assets/generate — Start GEO Generation

> Submit a URL to generate 7 GEO files that help AI crawlers understand your brand. Returns a jobId to poll for completion. Costs 20 credits.

The GEO Assets generation endpoint accepts your website URL and kicks off an asynchronous 4-stage pipeline — Page Discovery, Content Crawl, Enhanced Asset Generation, and Final Report. Because the job can take several minutes, the endpoint returns immediately with a `jobId`. You then poll the status endpoint until the job is `completed`, then fetch the generated files.

<Warning>
  This endpoint deducts **20 credits** from your account when the job starts. Ensure your balance is sufficient before calling it.
</Warning>

## Start a generation job

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.cognerd.in/api/geo-assets/generate \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://yoursite.com"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.cognerd.in/api/geo-assets/generate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url: 'https://yoursite.com' })
  });
  const { jobId, status } = await response.json();
  console.log('Job started:', jobId);
  ```
</CodeGroup>

### Request body

<ParamField body="url" type="string" required>
  The root URL of the website to crawl and generate GEO files for. Must include the protocol (e.g. `https://yoursite.com`).
</ParamField>

### Response

```json theme={null}
{
  "jobId": "geo_abc123",
  "status": "queued"
}
```

<ResponseField name="jobId" type="string">
  Unique identifier for this generation job. Use it to poll status and retrieve results.
</ResponseField>

<ResponseField name="status" type="string">
  Initial job state — always `"queued"` on a successful submission.
</ResponseField>

## Poll for job status

Use `GET /api/geo-assets/job/:jobId/status` to check progress. Poll every 5–10 seconds until `status` is `"completed"` or `"failed"`.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.cognerd.in/api/geo-assets/job/geo_abc123/status \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  async function waitForGeoJob(jobId, token) {
    while (true) {
      await new Promise(r => setTimeout(r, 5000)); // wait 5 seconds

      const res = await fetch(
        `https://api.cognerd.in/api/geo-assets/job/${jobId}/status`,
        { headers: { 'Authorization': `Bearer ${token}` } }
      );
      const data = await res.json();

      console.log(`Progress: ${data.progress}% — ${data.stage}`);

      if (data.status === 'completed' || data.status === 'failed') {
        return data;
      }
    }
  }

  const result = await waitForGeoJob('geo_abc123', 'YOUR_TOKEN');
  ```
</CodeGroup>

### Status response

```json theme={null}
{
  "jobId": "geo_abc123",
  "status": "processing",
  "progress": 45,
  "stage": "generating"
}
```

<ResponseField name="status" type="string">
  One of `"queued"`, `"processing"`, `"completed"`, or `"failed"`.
</ResponseField>

<ResponseField name="progress" type="number">
  Completion percentage from 0 to 100.
</ResponseField>

<ResponseField name="stage" type="string">
  Current pipeline stage: `"discovering"`, `"crawling"`, `"generating"`, or `"complete"`.
</ResponseField>

## Generated files

When the job completes, seven files are available via the reports endpoints:

| File                  | Purpose                                              |
| --------------------- | ---------------------------------------------------- |
| `llms.txt`            | Machine-readable brand summary for AI agents         |
| `robots.txt`          | AI-aware crawl rules for LLM crawlers                |
| `sitemap.xml`         | Structured page index for AI crawlers                |
| `site.jsonld`         | Site entity schema (schema.org WebSite)              |
| `organization.jsonld` | Brand identity schema (schema.org Organization)      |
| `website.jsonld`      | Website schema with sitelinks search action          |
| `entities.json`       | Entity relationship graph (people, products, topics) |

## Error responses

| Status | Code                   | Meaning                                 |
| ------ | ---------------------- | --------------------------------------- |
| 401    | `UNAUTHORIZED`         | Missing or invalid Bearer token         |
| 402    | `INSUFFICIENT_CREDITS` | Fewer than 20 credits available         |
| 400    | `INVALID_URL`          | The `url` field is missing or malformed |
| 500    | `INTERNAL_ERROR`       | Job failed to start; retry the request  |