Create a Project

Creates a new scanning project. A project ties one creative — either a tag URL or an inline HTML payload — to a schedule, a location, and optional alert wiring. Once created, Pinokio scans the creative on the configured cadence and stores results against the returned project_id.

Endpoint

POST /v1/project/create

Authentication

Bearer token, obtained from /login.

Authorization: Bearer <access_token>

Request body

JSON object with the following fields:

Field	Type	Required	Description
`name`	string	Yes	Human-readable project name. Shown in the dashboard and on returned objects.
`demand_id`	string	Yes	Your identifier for the demand source — useful for grouping projects by partner or DSP.
`tag`	string	Yes	What to scan. Either a URL pointing at the creative (`https://…`) or a raw HTML string. See Tag formats below.
`scan_now`	number	No	`1` to run a scan immediately on create; `0` to wait for the schedule.
`times_per_day`	number	No	How many times per day the project is scanned. `1`, `2`, etc.
`alert_pixel`	string	No	URL Pinokio hits when a scan finds something. See Alert Pixel.
`locations`	string	No	Two-letter ISO country code to scan from (e.g. `US`, `GB`, `JP`).
`creative_id`	string	No	Your creative identifier — UUID or any string. Echoed back in results so you can join Pinokio data against your own.

Tag formats

tag accepts two shapes:

URL — a fully qualified URL that returns the creative when loaded. Pinokio’s scanner navigates to it and analyzes what renders.
HTML — a raw HTML string. Pinokio wraps it in a sandboxed browser and analyzes the rendered output. Useful when the creative is delivered through a tag macro and you don’t have a public URL.

curl -X POST "https://{pinokio-api-url}/v1/project/create" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test project",
    "demand_id": "124123132",
    "tag": "https://example.com/ad_path.html",
    "scan_now": 0,
    "times_per_day": 2,
    "alert_pixel": "https://example.com/some_endpoint_for_pixel",
    "locations": "US",
    "creative_id": "38400000-8cf0-11bd-b23e-10b96e40000d"
  }'

curl -X POST "https://{pinokio-api-url}/v1/project/create" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test project",
    "demand_id": "124123132",
    "tag": "<div id=\"wrapper_9e76c92081\"><html><body><img src=\"https://example.com/image.png\"/></body></html></div>",
    "scan_now": 1,
    "times_per_day": 1,
    "alert_pixel": "https://example.com/some_endpoint_for_pixel",
    "locations": "US",
    "creative_id": "38400000-8cf0-11bd-b23e-10b96e40000d"
  }'

Response

200 OK

{
  "status": "success",
  "message": "Project created successfuly!",
  "project_id": "b23e-8cf0-b23e-8cf0-12fa"
}

Store the project_id — you will need it to read scan results, fetch session detail, or delete the project later.

Errors

400 Bad Request

Detail	Cause
`Invalid session! Please try again.`	Access token is expired or invalid. Refresh and retry.
`Missing or invalid [{param}] parameter.`	A required field is missing or malformed. The detail message names the offending field.