Skip to content
Plune Plune Plune Docs

Ask a member to take the company over

POST
/v1/companies/{id}/handover
 
curl --request POST \
  --url https://beta-api.plune.ai/v1/companies/example/handover \
  --header 'Content-Type: application/json' \
  --cookie plune_session=<plune_session> \
  --data '{ "toUserId": "6f1c2b3a-0000-4000-8000-0000000000a2" }'

The owner only (ADR 0050 §3). Asks a member of the company to become the owner; nothing changes until they accept (POST /v1/handovers/{id}/accept), and they are told by mail, in the language of their profile, with the page to answer on — no token in it. Seven days to answer. One open request a company: a second is 409 handover_pending until the first is withdrawn, declined or runs out. Once accepted, the old owner is a manager of the company; its projects keep their own owners. Somebody outside the company gets the 404 an id nobody has; anybody else in it, 403 owner_only. The signed-in session alone: an API token gets 403 session_required — the owner holds the secrets, and a CI token neither asks for, answers nor reads a handover. Recorded in the company’s log.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string

An id from GET /v1/companies

Request Body required

Section titled “Request Body required ”
Media type application/json
object
toUserId
required

A member of the project — of a company’s project, of the company too — or of the company; not the owner

string
Example 
{
  "toUserId": "6f1c2b3a-0000-4000-8000-0000000000a2"
}

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Asked — waiting for the answer

Media type application/json
object
handover
required

A handover of ownership (ADR 0050 §3): the owner asks one member to take the project or the company over; nothing changes until that member accepts. Seven days to answer, then expired.

object
id
required
string format: uuid
toUserId
required

The member asked, as GET /v1/members (or the company page) lists them

string
state
required
string
Allowed values: pending accepted declined cancelled expired
expiresAt
required
string format: date-time
Example 
{
  "handover": {
    "id": "6f1c2b3a-0000-4000-8000-0000000000b9",
    "toUserId": "6f1c2b3a-0000-4000-8000-0000000000a2",
    "state": "pending",
    "expiresAt": "2026-08-04T09:00:00.000Z"
  }
}

400

Section titled “400 ”

Invalid body — a toUserId; or the owner named themself

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

401

Section titled “401 ”

No / invalid session

403

Section titled “403 ”

Somebody in the company who is not its owner, or an API token

Media type application/json
object
error
required
string
Examples
{
  "error": "company owner only",
  "code": "owner_only"
}

404

Section titled “404 ”

No such company among yours, or nobody of that id in it

Media type application/json
object
error
required
string
Example 
{
  "error": "member '6f1c2b3a-0000-4000-8000-0000000000a2' not found"
}

409

Section titled “409 ”

A request of this company is waiting for an answer already

Media type application/json
object
error
required
string
Example 
{
  "error": "a handover of this company is waiting for an answer already — withdraw it first",
  "code": "handover_pending"
}

429

Section titled “429 ”

Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

Headers

Section titled “Headers ”
Retry-After
integer

Seconds until the window rolls over