Projects

Projects are the individual tenants of the platform. Each project has its own database and data.

Endpoints
   GET /:project
   GET /server/projects
  POST /server/projects
DELETE /server/projects/:project

List Available Projects

Lists the available (public) projects in the API.

You can prevent projects from being returned in this endpoint by prefixing the config file of the project with private., for example: private.thumper.php for the thumper project.

TIP

This endpoint is always publicy accessible.

Parameters

No URL parameters available.

Query

No query parameters available.

Returns

Array of project key strings.

Endpoint
   GET /server/projects
Response
{
  "data": [
    "thumper",
    "thumper-staging",
    "monospace",
    "ranger"
  ],
  "public": true
}

Retrieve Project Info

Gets information like name, locale, accent color about the given project.

TIP

This endpoint is always publicy accessible. Logged in users get more information.

Parameters

project required

The project you're targetting.

Attributes

api.version authenticated string

Current version of the API in use.

api.requires2FA boolean

If the API requires 2FA for all its users.

api.database authenticated string

What database type is being used.

api.project_logo file object

Nested file information for the project's logo.

api.project_color string (hex)

Project's accent color.

api.project_foreground file object

Nested file information for the project's public page's foreground.

api.project_background file object

Nested file information for the project's public page's background.

api.project_public_note string

Nested file information for the project's public note.

api.default_locale string

Locale string of the default language for the application.

api.telemetry boolean

Whether or not the API is allowed to send anonymous tracking information.

api.project_name string

The name of the project.

server.max_upload_size authenticated string

Maximum upload size in bytes that the server can accept.

server.general.php_version authenticated string

Current version of PHP that's being used in the server.

server.general.php_api authenticated string

How PHP is being run.

Query

No query parameters available.

Returns

Object of project and server information.


Public Pages

The project_color, project_logo, project_foreground, project_background, and project_public_note are used to build out the public pages of the admin app, like the login page.

Endpoint
   GET /:project/
Response
{
  "data": {
    "api": {
      "version": "8.3.1",
      "requires2FA": false,
      "database": "mysql",
      "project_name": "Thumper",
      "project_logo": {
        "full_url": "https://demo.directus.io/uploads/thumper/originals/19acff06-4969-5c75-9cd5-dc3f27506de2.svg",
        "url": "/uploads/thumper/originals/19acff06-4969-5c75-9cd5-dc3f27506de2.svg"
      },
      "project_color": "#4CAF50",
      "project_foreground": {
        "full_url": "https://demo.directus.io/uploads/thumper/originals/f28c49b0-2b4f-571e-bf62-593107cbf2ec.svg",
        "url": "/uploads/thumper/originals/f28c49b0-2b4f-571e-bf62-593107cbf2ec.svg"
      },
      "project_background": {
        "full_url": "https://demo.directus.io/uploads/thumper/originals/03a06753-6794-4b9a-803b-3e1cd15e0742.jpg",
        "url": "/uploads/thumper/originals/03a06753-6794-4b9a-803b-3e1cd15e0742.jpg"
      },
      "telemetry": true,
      "default_locale": "en-US",
      "project_public_note": "**Welcome to the Directus Public Demo!**\n\nYou can sign in with `admin@example.com` and `password`. Occasionally users break things, but don’t worry… the whole server resets each hour."
    },
    "server": {
      "max_upload_size": 20971520,
      "general": {
        "php_version": "7.2.24-0ubuntu0.18.04.1",
        "php_api": "apache2handler"
      }
    }
  }
}

Create a Project

Create a new project. You are required to have an empty database and credentials to access it.

Parameters

No URL parameters available.

Attributes

project required string

Key for the project. This is used in the API URLs.

project_name optional string

Human friendly name for the project. Will be shown in the Directus admin app.

private optional boolean

Instantiate this project as a private project.

force optional boolean

Force the installation. This will overwrite whatever's there before. This will not alter any user created tables.

existing optional boolean

Overwrites existing Directus system collections. This will not alter any user created tables.

super_admin_token required string

The first time you create a project, the provided token will be saved and required for subsequent project installs. It can also be found and configured in /config/__api.json on your server.

db_host optional string

Host of the database. Defaults to localhost.

db_port optional integer

Port of the database. Defaults to 3306.

db_name required string

Name of the database you're connecting to.

db_user required string

Database user that has permission to modify your database.

db_password optional string

Password for the database user.

user_email required string

Email address of the first admin user of the platform. New users can be added later using the /users endpoint.

user_password required string

Password for the first admin user of the platform.

user_token optional string

A static token for the user that can be used as access token for the API.

Other Configuration Objects

cache, storage, auth, cors, and mail configuration settings can be provided in this endpoint as well. See the _example.php config file for more information.

Query

No query parameters available.

Returns

Empty payload with status 200 OK

Endpoint
  POST /server/projects
Request
{
  "project": "thumper",
  "super_admin_token": "very_secret_token",
  "db_name": "db",
  "db_user": "root",
  "db_password": "root",
  "user_email": "admin@example.com",
  "user_password": "password",
}

Delete a Project

WARNING

This will delete both the config file and empty the database. Use with extreme caution.

Delete an existing project

Parameters

project required

The project you're targetting.

Query

super_admin_token required string

The first time you create a project, the provided token will be saved and required for subsequent project installs. It can also be found and configured in /config/__api.json on your server.

Returns

Returns an empty body with HTTP status 204

Endpoint
DELETE /server/projects/:project