AthausDocs

Move listings into a project

Request, parameters, response and errors of POST /v1/projects/{externalProjectId}/assign.

Last updated:

Makes existing listings units of the project, up to 500 in one call, all or nothing. Each keeps its own data; its data.location.unit is the unit number and must be set and unique in the project (409 unit_already_exists, each item named by externalListingIds[n]). A listing that is a unit of another project is refused (400): release it there first. A listing whose unit status does not fit the project (a released sold unit into a rental project) is 409 unit_status_invalid. A listing that is a unit of this project already stays as it is, so a repeat changes nothing. A project holds at most 1000 units: a call that would pass that is 409 project_unit_limit_exceeded and changes nothing. Needs write access to projects.

Requires the scope propose and at least the level write on projects.

Request

POST https://api.athaus.ai/v1/projects/{externalProjectId}/assign

Parameters

Path

NameTypeRequiredDescription
externalProjectIdstringyesYour reference of the project: the value of metadata.source.offererMarketingKey. A project without one has its own projectId here, and the projectId always works in the path. 1 to 128 letters, digits, dots, underscores or hyphens, not starting or ending with a dot.

Header

NameTypeRequiredDescription
Athaus-VersionstringnoOptional and carries nothing a client needs: the version is the path. Accepted when it says v1 or 1. Any other value is a 400 api_version_unsupported.
Idempotency-KeystringnoMakes a retry safe: the same key with the same body returns the first answer and writes nothing twice. A random value of at least 128 bits, for example a UUID, 1 to 255 characters. The key is kept for 24 hours and scoped to the API key and this operation. The same key with a different body is a 422; while the first request still runs it is a 409. Only successful answers are kept: after an error the key is free again.

Request body

JSON with Content-Type: application/json. A field the API does not know is a 400, and errors[].name names the field. The body is required.

FieldTypeDescription
externalListingIdsstring[]The listings to move into the project or out of it. Each keeps its own data when it is assigned; a listing without data.location.unit cannot be assigned.

Example

curl -X POST "https://api.athaus.ai/v1/projects/PRJ-1-ext/assign" \
  -H "Authorization: Bearer ath_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"externalListingIds":["PRJ-7-WE-1","PRJ-7-WE-2"]}'

Response

On success the status is 202 with ProjectUnitsReceipt.

ProjectUnitsReceipt

FieldTypeDescription
requestIdstring
projectIdstring
externalProjectIdstring
listingsobject[]The listings the call created or moved, in the order of the request.
listings[].listingIdstring
listings[].externalListingIdstring
listings[].unitstring
warningsobject[]
warnings[].typestring
warnings[].messagestring

Response headers

HeaderDescription
Request-IdIdentifies this request. Quote it in a support request.
Athaus-VersionThe API version of this response: v1.
Athaus-ReleaseThe release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it.
RateLimit-PolicyThe quota policy of the bucket that applies.
RateLimitRemaining quota and seconds until the bucket is full again.
Idempotent-Replayedtrue when this is the stored answer to an earlier request with the same Idempotency-Key.

Errors

Every error arrives as problem details. Branch on code, not on title or detail.

StatusCodesMeaning
400api_version_unsupported, invalid_bodyInvalid request.
401unauthorizedMissing or invalid API key.
403insufficient_permissions, plan_requiredThe key lacks a right, or the plan does not include API access.
404not_foundNothing under this ID.
409unit_already_exists, project_unit_limit_exceededThe request conflicts with the state of the resource (for example a duplicate), or with an idempotency key.
413payload_too_largeThe request body is larger than 512 KB.
415invalid_inputThe request body is not JSON. Send Content-Type: application/json.
422idempotency_key_reusedThe idempotency key was already used with a different request body.
429rate_limitedRate limit exceeded.
500internal_errorServer error.

Keep reading

On this page