Projects

Project attributes

field	type	description
id	string	unique ID
name	string	name of the project
default	boolean	is this the default project?
created_at	date	creation date of the project
updated_at	date	last time the project has been updated
owner	object	information about the owner of the project
flags	object	list of flags associated to the project

Example object:

{
  "id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
  "name": "example-project",
  "default": false,
  "created_at": "2014-09-10T10:17:52.690+02:00",
  "updated_at": "2014-09-10T10:17:52.690+02:00",
  "owner": {
    "id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
    "username": "john",
    "email": "user@example.com",
    "flags": {
      "beta_user": true
    }
  },
  "flags": {
    "beta_user": true
  }
}

Create a Project

POST https://$SCALINGO_API_URL/v1/projects

Parameters

project.name: Name of the project
project.default: (Optional) Set to true to make this the default project

Example

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/projects -d \
  '{
    "project": {
      "name": "example-project",
      "default": true
    }
  }'

Returns 201 Created

{
  "project": {
    "id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
    "name": "example-project",
    "default": true,
    "created_at": "2014-09-10T10:17:52.690+02:00",
    "updated_at": "2014-09-10T10:17:52.690+02:00",
    "owner": {
      "id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
      "username": "john",
      "email": "user@example.com",
      "flags": {
        "beta_user": true
      }
    },
    "flags": {
      "beta_user": true
    }
  }
}

List Your Projects

GET https://$SCALINGO_API_URL/v1/projects

List all your projects.

Example

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/projects

Returns 200 OK

{
  "projects": [
    {
      "id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
      "name": "example-project",
      "default": true,
      "created_at": "2014-09-10T10:17:52.690+02:00",
      "updated_at": "2014-09-10T10:17:52.690+02:00",
      "owner": {
        "id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
        "username": "john",
        "email": "user@example.com",
        "flags": {
          "beta_user": true
        }
      },
      "flags": {
        "beta_user": true
    }
    }, {
      "id": "pr-91b4dbd6-2c36-584f-c44d-7383c98f747g",
      "name": "another-project",
      "default": false,
      "created_at": "2014-09-11T10:17:52.690+02:00",
      "updated_at": "2014-09-11T10:17:52.690+02:00",
      "owner": {
        "id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
        "username": "john",
        "email": "user@example.com",
        "flags": {
          "beta_user": true
        }
      }
    }
  ]
}

Get a precise Project

GET https://$SCALINGO_API_URL/v1/projects/[:project_id]

Display a precise project

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/projects/pr-82a3cac5-9b25-473e-b33d-6272b87e636f

Returns 200 OK

{
  "project": {
    "id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
    "name": "example-project",
    "default": false,
    "created_at": "2014-09-10T10:17:52.690+02:00",
    "updated_at": "2014-09-10T10:17:52.690+02:00",
    "owner": {
      "id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
      "username": "john",
      "email": "user@example.com",
      "flags": {
        "beta_user": true
      }
    },
    "flags": {
      "beta_user": true
    }
  }
}

Update a Project

PATCH https://$SCALINGO_API_URL/v1/projects/[:project_id]

Parameters

project.name: (Optional) New name of the project
project.default: (Optional) Set to true to make this the default project

Note: project.default cannot be changed from true to false. To change the default project, update an existing project to be the new default one, or create a new default project.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X PATCH https://$SCALINGO_API_URL/v1/projects/pr-82a3cac5-9b25-473e-b33d-6272b87e636f -d \
  '{
    "project": {
      "name": "updated-project-name",
      "default": true
    }
  }'

Returns 200 OK

{
  "project": {
    "id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
    "name": "updated-project-name",
    "default": true,
    "created_at": "2014-09-10T10:17:52.690+02:00",
    "updated_at": "2014-09-10T11:25:30.123+02:00",
    "owner": {
      "id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
      "username": "john",
      "email": "user@example.com",
      "flags": {
        "beta_user": true
      }
    },
    "flags": {
      "beta_user": true
    }
  }
}

Delete a Project

DELETE https://$SCALINGO_API_URL/v1/projects/[:project_id]

Delete a project

Note: The project must not contain any applications. If the project contains applications, you must delete them first.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X DELETE "https://$SCALINGO_API_URL/v1/projects/pr-82a3cac5-9b25-473e-b33d-6272b87e636f"

Returns 204 No Content

{}

Project transfer invitations

Project transfer invitations let a project owner transfer ownership to another collaborator.

Transfer invitation attributes

field	type	description
id	string	unique ID of the invitation
project_id	string	ID of the project targeted by the transfer
invited_user_id	string	invited collaborator
invited_user_name	string	username of the invited collaborator
inviter_user_id	string	user who created the invitation
status	string	one of `pending`, `accepted`, `declined`, `canceled`, `failed`, `error`
status_reason	string	reason of transfer action failure
expires_at	date	expiration date of the invitation
created_at	date	creation date
updated_at	date	last update date

Note: If the invitation status is error after acceptance, you’ll need to contact support to fix the transfer.

Example object:

{
  "id": "tin-01234567-89ab-cdef-0123-456789abcdef",
  "project_id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
  "invited_user_id": "us-f456a6c1-54d8-4a32-9d61-5f3c8e9d016a",
  "invited_user_name": "alice",
  "inviter_user_id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
  "status": "pending",
  "status_reason": "",
  "expires_at": "2014-09-13T10:17:52.690+02:00",
  "created_at": "2014-09-10T10:17:52.690+02:00",
  "updated_at": "2014-09-10T10:17:52.690+02:00"
}

List all your project transfer invitations

GET https://$SCALINGO_API_URL/v1/projects/[:project_id]/transfer_invitations

By default only not expired pending invitations are returned. Pass the status query parameter (for example ?status=all) to disable the pending-only filter.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/projects/pr-82a3cac5-9b25-473e-b33d-6272b87e636f/transfer_invitations

Returns 200 OK

{
  "transfer_invitations": [
    {
      "id": "tin-01234567-89ab-cdef-0123-456789abcdef",
      "project_id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
      "invited_user_id": "us-f456a6c1-54d8-4a32-9d61-5f3c8e9d016a",
      "invited_user_name": "alice",
      "inviter_user_id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
      "status": "pending",
      "status_reason": "",
      "expires_at": "2014-09-13T10:17:52.690+02:00",
      "created_at": "2014-09-10T10:17:52.690+02:00",
      "updated_at": "2014-09-10T10:17:52.690+02:00"
    }
  ]
}

Get a project transfer invitation

GET https://$SCALINGO_API_URL/v1/projects/[:project_id]/transfer_invitations/[:id]

Retrieve a specific project transfer invitation. The invitation is visible to the inviter or the invited collaborator.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/projects/pr-82a3cac5-9b25-473e-b33d-6272b87e636f/transfer_invitations/tin-01234567-89ab-cdef-0123-456789abcdef

Returns 200 OK

{
  "transfer_invitation": {
    "id": "tin-01234567-89ab-cdef-0123-456789abcdef",
    "project_id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
    "invited_user_id": "us-f456a6c1-54d8-4a32-9d61-5f3c8e9d016a",
    "invited_user_name": "alice",
    "inviter_user_id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
    "status": "pending",
    "status_reason": "",
    "expires_at": "2014-09-13T10:17:52.690+02:00",
    "created_at": "2014-09-10T10:17:52.690+02:00",
    "updated_at": "2014-09-10T10:17:52.690+02:00"
  }
}

List Eligible New Owners for Project Transfer

GET https://$SCALINGO_API_URL/v1/projects/[:project_id]/eligible_new_owners

List all users eligible to become the new owner of a project. Only the current project owner can call this endpoint. To be eligible, a user must be a collaborator on all resources within the project.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/projects/pr-82a3cac5-9b25-473e-b33d-6272b87e636f/eligible_new_owners

Returns 200 OK

{
  "eligible_new_owners": [
    {
      "user_name": "john",
      "user_id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63"
    },
    {
      "user_name": "alice",
      "user_id": "us-f456a6c1-54d8-4a32-9d61-5f3c8e9d016a"
    }
  ]
}

Create a project transfer invitation

POST https://$SCALINGO_API_URL/v1/projects/[:project_id]/transfer_invitations

Project owners can create a transfer invitation for a collaborator who has access to all applications in the project. The API sets the expiration (expires_at) to now + 3 days and fails if a pending invitation already exists for the project.

Parameters

transfer_invitation.invited_user_id: ID of the collaborator to invite

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/projects/pr-82a3cac5-9b25-473e-b33d-6272b87e636f/transfer_invitations -d \
  '{
    "transfer_invitation": {
      "invited_user_id": "us-f456a6c1-54d8-4a32-9d61-5f3c8e9d016a"
    }
  }'

Returns 201 Created

{
  "transfer_invitation": {
    "id": "tin-01234567-89ab-cdef-0123-456789abcdef",
    "project_id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
    "invited_user_id": "us-f456a6c1-54d8-4a32-9d61-5f3c8e9d016a",
    "invited_user_name": "alice",
    "inviter_user_id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
    "status": "pending",
    "status_reason": "",
    "expires_at": "2014-09-13T10:17:52.690+02:00",
    "created_at": "2014-09-10T10:17:52.690+02:00",
    "updated_at": "2014-09-10T10:17:52.690+02:00"
  }
}

Accept a project transfer invitation

POST https://$SCALINGO_API_URL/v1/projects/[:project_id]/transfer_invitations/[:id]/accept

The invited collaborator can accept a project transfer invitation.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/projects/pr-82a3cac5-9b25-473e-b33d-6272b87e636f/transfer_invitations/tin-01234567-89ab-cdef-0123-456789abcdef/accept

Returns 200 OK

{
  "transfer_invitation": {
    "id": "tin-01234567-89ab-cdef-0123-456789abcdef",
    "project_id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
    "invited_user_id": "us-f456a6c1-54d8-4a32-9d61-5f3c8e9d016a",
    "invited_user_name": "alice",
    "inviter_user_id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
    "status": "accepted",
    "status_reason": "",
    "expires_at": "2014-09-13T10:17:52.690+02:00",
    "created_at": "2014-09-10T10:17:52.690+02:00",
    "updated_at": "2014-09-10T11:00:00.000+02:00"
  }
}

Decline a project transfer invitation

POST https://$SCALINGO_API_URL/v1/projects/[:project_id]/transfer_invitations/[:id]/decline

The invited collaborator can decline a project transfer invitation.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/projects/pr-82a3cac5-9b25-473e-b33d-6272b87e636f/transfer_invitations/tin-01234567-89ab-cdef-0123-456789abcdef/decline

Returns 200 OK

{
  "transfer_invitation": {
    "id": "tin-01234567-89ab-cdef-0123-456789abcdef",
    "project_id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
    "invited_user_id": "us-f456a6c1-54d8-4a32-9d61-5f3c8e9d016a",
    "invited_user_name": "alice",
    "inviter_user_id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
    "status": "declined",
    "status_reason": "",
    "expires_at": "2014-09-13T10:17:52.690+02:00",
    "created_at": "2014-09-10T10:17:52.690+02:00",
    "updated_at": "2014-09-10T11:00:00.000+02:00"
  }
}

Cancel a project transfer invitation

POST https://$SCALINGO_API_URL/v1/projects/[:project_id]/transfer_invitations/[:id]/cancel

The project’s owner can cancel a project transfer invitation.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/projects/pr-82a3cac5-9b25-473e-b33d-6272b87e636f/transfer_invitations/tin-01234567-89ab-cdef-0123-456789abcdef/cancel

Returns 200 OK

{
  "transfer_invitation": {
    "id": "tin-01234567-89ab-cdef-0123-456789abcdef",
    "project_id": "pr-82a3cac5-9b25-473e-b33d-6272b87e636f",
    "invited_user_id": "us-f456a6c1-54d8-4a32-9d61-5f3c8e9d016a",
    "invited_user_name": "alice",
    "inviter_user_id": "us-c1a410ff-d68f-4c94-9a83-c3dedf866d63",
    "status": "canceled",
    "status_reason": "",
    "expires_at": "2014-09-13T10:17:52.690+02:00",
    "created_at": "2014-09-10T10:17:52.690+02:00",
    "updated_at": "2014-09-10T11:00:00.000+02:00"
  }
}