API › Projects

Add a site

Adds an address to a project: a subdomain (app., api.) or another domain of the same product.

POSThttps://api.rustine.io/v1/projects/{project_id}/targets

OAuth permission: scans:run · an API key has them all

Only a site you own or are allowed to test. How many addresses a project holds depends on the plan (5 on Solo, 20 on Pro): past that, 402 address_limit_reached.

Path parameters

project_idstringrequired
Project id.

Headers

Idempotency-Keystringoptional
A unique key (1 to 255 printable characters, a UUID is fine) to retry this request safely: the first response is replayed for 24 hours; the same key with another request answers 409 idempotency_conflict.

Request body

urlstringrequired
Address of the site (https://app.example.com). Only a site you own or are allowed to test.

Response

idstring
Target id: a site (domain) or a GitHub repository of the project.
objectstring
project_idstring
Project the target belongs to.
kindstring
domain (a site) or repository.
domainserverrepository
addressstring
Hostname of a site (app.example.com) or owner/repo of a repository.
verifiedboolean
Whether the workspace proved it controls this target. Without proof, issue details stay hidden and only quick scans run.
scorenumber | null
Score out of 100; null before the first finished scan.
gradestring | null
Grade from A to F; null before the first finished scan.
ABCDF
last_scan_atstring | null
End of the last finished scan.
hidden_issuesobject | null
Unverified site: what its hidden issues amount to, counts only (never which, nor where). Null when nothing is hidden.
- urgentinteger
  Open critical and high issues hidden until the site is verified.
- laterinteger
  Open medium and low issues hidden until the site is verified.

Errors

Status	error.code	What happens
400	body_invalid	The request body is not valid JSON. Check the `Content-Type: application/json` header.
400	parameter_invalid	A parameter is missing or invalid; `param` names it.
400	url_invalid	The address is not the valid URL of a public site.
400	url_private	Rustine only scans public sites, never a local or private address.
400	idempotency_key_invalid	The `Idempotency-Key` header must be 1 to 255 printable characters.
401	authentication_required	No key in the request. Pass it in the `Authorization: Bearer rst_…` header, never in the address.
401	invalid_api_key	The key or OAuth token is wrong, revoked or expired. Check it is copied in full, or create a new key.
402	api_plan_required	The workspace is on the Free plan. The API comes with Pro, or on a 14-day trial with Solo.
402	api_trial_ended	Solo's 14-day trial is over. Move to Pro: your keys work again at once.
402	address_limit_reached	The project already follows as many addresses as your plan allows.
402	domain_taken	On the Free plan, a domain another free account already follows cannot be added or scanned.
402	project_paused	The project is paused: your plan covers fewer projects than your workspace has. Its issues stay readable, but nothing new runs.
403	scope_missing	The OAuth token lacks the permission this route needs (shown on its page). Reconnect the agent to grant it. An API key has every permission.
404	resource_not_found	Nothing with this id in the key's workspace. An object of another workspace answers the same: its existence is never revealed.
409	site_excluded	The owner of this site asked not to be scanned. Rustine will not scan it.
409	target_exists	The project already follows this address.
409	idempotency_conflict	This `Idempotency-Key` was already used for another request (method, path or body). A new action takes a new key.
409	idempotency_in_progress	A request with this `Idempotency-Key` is still running. Retry in a moment.
429	rate_limited	Too many requests for this key (120 per minute). Wait `Retry-After` seconds.
500	internal_error	An error on our side, reported automatically. Retry later; give the `Request-Id` to support if it comes back.
503	service_unavailable	Rustine is unavailable for a moment. Retry with the same `Idempotency-Key`.