> ## Documentation Index
> Fetch the complete documentation index at: https://superflow-claude-superflow-portal-docs-78gpp8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Project

Use this API to create a website project on Superflow. Creating the same URL twice resolves to the same project, so the call is safe to repeat.

# Endpoint

`POST https://createproject.api.velt.dev/`

# Headers

<ParamField header="x-superflow-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-superflow-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body Example

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="projectUrl" type="string" required>
      Project URL, for example `https://yourprojecturl.com`
    </ParamField>

    <ParamField body="projectName" type="string" required>
      Project Name
    </ParamField>

    <ParamField body="scriptAlreadyInstalled" type="boolean">
      Set `true` when the Superflow script is already on the site, for example because your platform injects it for every project. The project is created as installed, and the duplicate-install check is skipped.
    </ParamField>

    <ParamField body="runAgentChecks" type="boolean">
      Set `true` to run AI agent checks against the site right after the project is created. Runs spend [AI credits](/billing/ai-credits).
    </ParamField>

    <ParamField body="agentIds" type="string[]">
      Which agents to run when `runAgentChecks` is `true`, up to 10. Defaults to the essential suite: `spell-check`, `lorem-ipsum`, `lighthouse`, `broken-links`, `accessibility-checker`. Ignored when `runAgentChecks` is not `true`.
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

```JSON theme={null}
{
  "data": {
    "projectUrl": "https://yourprojecturl.com",
    "projectName": "Your Project Name"
  }
}
```

With agent checks:

```JSON theme={null}
{
  "data": {
    "projectUrl": "https://yourprojecturl.com",
    "projectName": "Your Project Name",
    "runAgentChecks": true,
    "agentIds": ["spell-check", "broken-links"]
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Created new project successfully.",
    "data": {
      "projectId": "7649736893876327"
    }
  }
}
```

When `runAgentChecks` is `true`, `data` also contains an `agentChecks` block. `executionIds` are runs that started (not finished), and `failedAgentIds` lists any requested agents that could not start. Agent check failures never fail the create.

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Created new project successfully.",
    "data": {
      "projectId": "7649736893876327",
      "agentChecks": {
        "requested": ["spell-check", "broken-links"],
        "executionIds": ["exec_abc123", "exec_def456"],
        "failedAgentIds": []
      }
    }
  }
}
```

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

Common failures:

| Status               | Message                                        | Meaning                                                                                            |
| -------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `INVALID_ARGUMENT`   | `Api key not found.` / `Auth token not found.` | A required header is missing.                                                                      |
| `INVALID_ARGUMENT`   | `Invalid Api key.` / `Invalid Auth token.`     | The credentials do not match a workspace.                                                          |
| `INVALID_ARGUMENT`   | `Project url not valid!`                       | The URL could not be parsed.                                                                       |
| `INVALID_ARGUMENT`   | `SuperFlow project detected`                   | The site already has Superflow installed. Pass `scriptAlreadyInstalled: true` if that is expected. |
| `ALREADY_EXISTS`     |                                                | A project already exists for this domain.                                                          |
| `RESOURCE_EXHAUSTED` |                                                | The workspace has reached its project limit.                                                       |

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "status": "success",
      "message": "Created new project successfully.",
      "data": {
        "projectId": "7649736893876327"
      }
    }
  }
  ```
</ResponseExample>