# Projects

List, create, update, and delete the Screpy projects available to your REST API key.

## [Discover project IDs first](/content/docs/api/projects#discover-project-ids-first/index.html)

List projects before calling project-specific endpoints. Use the returned `project_uid`, not a display name, for [crawls](/content/docs/api/crawls/index.html), crawl data, comparisons, and health requests.

The list can include projects owned by the account and projects shared with it. Confirm the project scope before updating or deleting a project, especially in an automation that acts on more than one account. Use [account](/content/docs/api/account/index.html) when the workflow also depends on current allowances.

## [List accessible projects](/content/docs/api/projects#list-accessible-projects/index.html)

GET`/projects`

List projects available to the authenticated member, including shared team projects.

### [Authorization](/content/docs/api/projects#authorization/index.html)

`bearerApiKey`

AuthorizationBearer <token>

Create a REST API key in Settings > Connected Apps. MCP credentials do not authenticate this API.

In: `header`

### [Query Parameters](/content/docs/api/projects#parameters-query/index.html)

- **limit**?integer  
 Maximum records to return. Defaults to 50.  
 Range `1 <= value <= 100`  
 Default `50`

- **cursor**?string  
 Opaque cursor returned by the prior response. Do not construct or alter it.  
 Length `length <= 512`

### [Response Body](/content/docs/api/projects#response-body/index.html)

### 200  `application/json`

### 401  `application/json`

### 403  `application/json`

### 422  `application/json`

### 429  `application/json`

```curl
curl -X GET "https://api.screpy.com/v1/projects"
```

200401403422429

```json
{
  "data": [
    {
      "uid": "string",
      "name": "string",
      "domain": "string",
      "role": "owner",
      "crawler_enabled": true,
      "crawl_count": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "links": {
    "first": "http://example.com",
    "last": "http://example.com",
    "prev": "http://example.com",
    "next": "http://example.com"
  },
  "meta": {
    "path": "http://example.com",
    "per_page": 0,
    "next_cursor": "string",
    "prev_cursor": "string"
  }
}
```

```json
{
  "message": "Unauthenticated."
}
```

```json
{
  "message": "string",
  "code": "string"
}
```

```json
{
  "message": "string",
  "code": "string",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
```

```json
{
  "message": "string",
  "code": "string"
}
```

## [Create a project](/content/docs/api/projects#create-a-project/index.html)

POST`/projects`

Creates an owned project. Capacity, duplicate-domain, and plan checks run at request time.

### [Authorization](/content/docs/api/projects#authorization/index.html)

`bearerApiKey`

AuthorizationBearer <token>

Create a REST API key in Settings > Connected Apps. MCP credentials do not authenticate this API.

In: `header`

### [Request Body](/content/docs/api/projects#request-body/index.html)

`application/json`

**name** *string  
 Length `length <= 255`

**domain** *string  
 Reachable hostname without a path. `www.` is normalized away.  
 Length `length <= 255`

**country**? string | null  
 Supported country code.

**language**? string | null  
 Supported language code.

**timezone**? string | null  
 Length `length <= 64`

**crawler_max_urls**? integer  
 Must be allowed by the account's crawler-page allowance.  
 Range `1 <= value`

**crawler_depth**? integer  
 Range `1 <= value <= 10`

**crawler_follow_links**? boolean

**crawler_allow_external_links**? boolean

**crawler_connect_images**? boolean

**crawler_connect_links**? boolean

**uptime_enabled**? boolean

**notification_email**? string | null  
 Format `email`  
 Length `length <= 255`

### [Response Body](/content/docs/api/projects#response-body/index.html)

### 201  `application/json`

### 401  `application/json`

### 403  `application/json`

### 409  `application/json`

### 422  `application/json`

### 429  `application/json`

### 503  `application/json`

```curl
curl -X POST "https://api.screpy.com/v1/projects" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "domain": "string"
  }'
```

201401403409422429503

```json
{
  "data": {
    "uid": "string",
    "name": "string",
    "domain": "string",
    "role": "owner",
    "crawler_enabled": true,
    "crawl_count": 0,
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}
```

```json
{
  "message": "Unauthenticated."
}
```

```json
{
  "message": "string",
  "code": "string"
}
```

```json
{
  "message": "string",
  "code": "string"
}
```

```json
{
  "message": "string",
  "code": "string",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
```

```json
{
  "message": "string",
  "code": "string"
}
```

## [Get a project overview](/content/docs/api/projects#get-a-project-overview/index.html)

GET`/projects/{project_uid}`

Returns the project, its latest completed crawl summary, and current on-page overview.

### [Authorization](/content/docs/api/projects#authorization/index.html)

`bearerApiKey`

AuthorizationBearer <token>

Create a REST API key in Settings > Connected Apps. MCP credentials do not authenticate this API.

In: `header`

### [Path Parameters](/content/docs/api/projects#parameters-path/index.html)

**project_uid** *string  
 Accessible project UID. Discover it with `GET /projects`; do not guess it.  
 Match `^[a-z0-9]{10}$`

### [Response Body](/content/docs/api/projects#response-body/index.html)

### 200  `application/json`

### 401  `application/json`

### 403  `application/json`

### 404  `application/json`

### 429  `application/json`

```curl
curl -X GET "https://api.screpy.com/v1/projects/string"
```

200401403404429

```json
{
  "data": {
    "project": {
      "uid": "string",
      "name": "string",
      "domain": "string",
      "role": "owner",
      "crawler_enabled": true,
      "crawl_count": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    },
    "latest_completed_crawl": {
      "crawl_uid": "string",
      "status": "string",
      "state": "string",
      "status_label": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "finished_at": "2019-08-24T14:15:22Z",
      "last_synced_at": "2019-08-24T14:15:22Z",
      "progress": {
        "pages_crawled": 0,
        "pages_total": 0,
        "max_pages": 0,
        "current_depth": 0
      },
      "health": {
        "score": 0,
        "confidence": 0,
        "coverage": 0
      },
      "issues": {
        "critical": 0,
        "warnings": 0,
        "notices": 0,
        "total": 0
      },
      "totals": {
        "pages": 0,
        "indexable_pages": 0,
        "noindex_pages": 0,
        "links": 0,
        "images": 0,
        "unique_urls": 0
      }
    },
    "on_page": {
      "summary": {
        "status": "string",
        "finished_at": "2019-08-24T14:15:22Z",
        "health_score": 0,
        "health_score_version": 0,
        "health_score_confidence": 0,
        "health_score_coverage": 0,
        "health_score_groups": [
          null
        ],
        "health_score_delta": 0,
        "pages_total": 0,
        "critical_issues": 0,
        "warnings": 0,
        "notices": 0,
        "issues_total": 0,
        "avg_response_time_ms": 0,
        "duration_seconds": 0,
        "broken_links": 0,
        "total_images_count": 0,
        "missing_metadata": 0,
        "issues_added": 0,
        "issues_fixed": 0
      },
      "trends": [
        null
      ],
      "groups": [
        null
      ],
      "coverage": [
        null
      ]
    }
  }
}
```

```json
{
  "message": "Unauthenticated."
}
```

```json
{
  "message": "string",
  "code": "string"
}
```

```json
{
  "message": "Project not found or not accessible."
}
```

```json
{
  "message": "string",
  "code": "string"
}
```

## [Update supported project settings](/content/docs/api/projects#update-supported-project-settings/index.html)

PATCH`/projects/{project_uid}`

Send only fields to update. Unknown fields and unsupported nested rule fields are rejected.

### [Authorization](/content/docs/api/projects#authorization/index.html)

`bearerApiKey`

AuthorizationBearer <token>

Create a REST API key in Settings > Connected Apps. MCP credentials do not authenticate this API.

In: `header`

### [Path Parameters](/content/docs/api/projects#parameters-path/index.html)

**project_uid** *string  
 Accessible project UID. Discover it with `GET /projects`; do not guess it.  
 Match `^[a-z0-9]{10}$`

### [Request Body](/content/docs/api/projects#request-body/index.html)

`application/json`

**Properties** `1 <= properties`

- **name**? string  
 Length `length <= 255`

- **country**? string  
 Supported country code.  
 Length `length <= 2`

- **language**? string  
 Supported language code.  
 Length `length <= 16`

- **timezone**? string  
 Length `length <= 64`

- **crawler_enabled**? boolean

- **crawler_max_urls**? integer  
 Must be allowed by the billing account's crawler-page allowance.  
 Range `1 <= value`

- **crawler_depth**? integer  
 Range `1 <= value <= 10`

- **crawler_concurrency**? integer  
 Value in 
- 1  
- 2  
- 5  
- 10  
- 20

- **crawler_delay_seconds**? integer  
 Value in
- 0  
- 1  
- 5  
- 10  
- 30  
- 60

- **crawler_follow_links**? boolean

- **crawler_allow_external_links**? boolean

- **crawler_javascript_enabled**? boolean

- **crawler_connect_images**? boolean

- **crawler_connect_links**? boolean

- **rank_tracker_frequency**? string  
 Value in 
- "daily"  
- "weekly"  
- "biweekly"  
- "monthly"

- **map_tracker_frequency**? string  
 Availability of `daily` is plan-dependent.  
 Value in 
- "daily"  
- "weekly"  
- "biweekly"  
- "monthly"

- **uptime_enabled**? boolean

- **uptime_check_interval_minutes**? integer  
 Range `1 <= value <= 60`

- **notification_email**? string | null  
 Format `email`  
 Length `length <= 255`

- **map_tracker_match_rules**? array<MapTrackerMatchRule> | null  
 Items `items <= 10`

### [Response Body](/content/docs/api/projects#response-body/index.html)

### 200  `application/json`

### 401  `application/json`

### 403  `application/json`

### 404  `application/json`

### 422  `application/json`

### 429  `application/json`

### 503  `application/json`

```curl
curl -X PATCH "https://api.screpy.com/v1/projects/string" \
  -H "Content-Type: application/json" \
  -d '{}'
```

200401403404422429503

```json
{
  "message": "Unauthenticated."
}
```

```json
{
  "message": "string",
  "code": "string"
}
```

```json
{
  "message": "Project not found or not accessible."
}
```

```json
{
  "message": "string",
  "code": "string",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
```

```json
{
  "message": "string",
  "code": "string"
}
```

## [Permanently delete an owned project](/content/docs/api/projects#permanently-delete-an-owned-project/index.html)

DELETE`/projects/{project_uid}`

Only the project owner can delete a project.

### [Authorization](/content/docs/api/projects#authorization/index.html)

`bearerApiKey`

AuthorizationBearer <token>

Create a REST API key in Settings > Connected Apps. MCP credentials do not authenticate this API.

In: `header`

### [Path Parameters](/content/docs/api/projects#parameters-path/index.html)

**project_uid** *string  
 Accessible project UID. Discover it with `GET /projects`; do not guess it.  
 Match `^[a-z0-9]{10}$`

### [Response Body](/content/docs/api/projects#response-body/index.html)

### 204

### 401  `application/json`

### 403  `application/json`

### 404  `application/json`

### 429  `application/json`

### 503  `application/json`

```curl
curl -X DELETE "https://api.screpy.com/v1/projects/string"
```

204401403404429503

Empty

```json
{
  "message": "Unauthenticated."
}
```

```json
{
  "message": "string",
  "code": "string"
}
```

```json
{
  "message": "Project not found or not accessible."
}
```

```json
{
  "message": "string",
  "code": "string"
}

```