Getting Started¶

Environments¶

vScrawl is typically deployed per-customer/per-environment. Every example on this site uses a placeholder host:

https://{host}/...

Replace {host} with your environment's hostname (e.g. app.vscrawl.com, or a staging equivalent). There is no shared multi-tenant public API host — each deployment is its own environment.

Content types¶

JSON request/response bodies: Content-Type: application/json.
File uploads (document upload, branding assets): multipart/form-data. These endpoints are called out explicitly in their reference pages.
File downloads (signed PDF, evidence report, Power Survey CSV export): raw binary with the appropriate Content-Type/Content-Disposition response headers.

Pagination¶

List endpoints across the API (Documents, Templates, Organization Users, custom Roles) use the same convention — a page/size request and a Page<T> response body:

Request query parameters:

Param	Type	Description
`page`	integer	Zero-based page index. Default `0`.
`size`	integer	Page size. Default `20` unless a specific endpoint documents otherwise.
`sort`	string, repeatable	`field,asc` or `field,desc`. Can be repeated for multi-field sort.

Response shape:

{
  "content": [ /* array of items */ ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 20,
    "sort": { "sorted": false, "unsorted": true }
  },
  "totalElements": 137,
  "totalPages": 7,
  "number": 0,
  "numberOfElements": 20,
  "size": 20,
  "first": true,
  "last": false,
  "empty": false
}

Most list endpoints also accept one or more searchValue/entity-specific filter query parameters alongside pagination — these are documented per endpoint.

Dates¶

Timestamps in request/response bodies (auto-delegation windows, field-event timestamps, consent capture) are ISO-8601 instants, e.g. 2026-08-01T09:30:00Z.

Before you call anything else¶

Read these in order:

Concepts & Glossary — the object model. Most confusion traces back to workflows vs. documents, or to the status lifecycle.
Authentication — every endpoint needs one of a few mechanisms, depending on who's calling.
Errors & Response Format — how failures are shaped, so you can handle them consistently.