Creating and Using Droplets

Droplets allow third-party services to be used with the Fluid platform. Each Droplet is created and maintained by its creator company. Droplets can be used internally by the creator company or can be made available for use by other companies in the Droplet Marketplace.

Creating a Droplet

To create a Droplet, you need to have a Fluid account with access to the Fluid API.

Once you have access to the Fluid API, you can create a Droplet by making a POST request to the /api/droplets endpoint.

curl -i -X POST \
  https://myco.fluid.app/api/droplets \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "droplet": {
      "name": "string",
      "embed_url": "string",
      "settings": {
        "marketplace_page": {
          "title": "string",
          "summary": "string",
          "logo_url": "string"
        },
        "details_page": {
          "title": "string",
          "summary": "string",
          "logo_url": "string",
          "features": [
            {
              "name": "string",
              "summary": "string",
              "details": "string",
              "image_url": "string",
              "video_url": "string"
            }
          ]
        },
        "service_operational_countries": [
          "string"
        ]
      }
    }
  }'

A payload for creating a Droplet could look like this:

{
  "droplet": {
    "name": "My Droplet",
    "embed_url": "https://my-company.com/embed",
    "active": true,
    "settings": {
      "marketplace_page": {
        "title": "My Droplet",
        "summary": "A Droplet for my company",
        "logo_url": "https://my-company.com/logo.svg",
      },
      "details_page": {
        "title": "My Droplet",
        "summary": "A Droplet for my company",
        "logo": "https://my-company.com/big-logo.svg",
        "features": [
          {
            "name": "Feature 1",
            "summary": "Feature 1 summary",
            "details": "Feature 1 details",
            "video_url": "https://my-company.com/feature-1.mp4"
          },
          {
            "name": "Feature 2",
            "summary": "Feature 2 summary",
            "details": "Feature 2 details",
            "image_url": "https://my-company.com/feature-2.svg"
          },
        ]
      }
    }
  }
}

name
The name of the Droplet

embed_url
The URL of the page that will be embedded in the Fluid platform. When a company is using the Droplet, this is the page that will be shown to that company (in an iframe with the company's ID appended to the URL).

active
Whether the Droplet is active and can be used.

The settings determine how the Droplet will be displayed in the Fluid Marketplace

and what its individual details page will look like.

Note: Droplets won't be available in the Marketplace until they are approved by Fluid.

Updating a Droplet

To update a Droplet, you can make a PUT request to the /api/droplets/:droplet_uuid endpoint.

curl -i -X PUT \
  'https://myco.fluid.app/api/droplets/{uuid}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "droplet": {
      "name": "string",
      "embed_url": "string",
      "settings": {
        "marketplace_page": {
          "title": "string",
          "summary": "string",
          "logo_url": "string"
        },
        "details_page": {
          "title": "string",
          "summary": "string",
          "logo_url": "string",
          "features": [
            {
              "name": "string",
              "summary": "string",
              "details": "string",
              "image_url": "string",
              "video_url": "string"
            }
          ]
        },
        "service_operational_countries": [
          "string"
        ]
      }
    }
  }'

A payload for updating a Droplet could look like this:

{
  "droplet": {
    "name": "My Updated Droplet",
    "embed_url": "https://my-company.com/embed-updated",
    "active": false,
    "settings": {
      "marketplace_page": {
        "title": "My Updated Droplet",
        "summary": "A Droplet for my company",
        "logo_url": "https://my-company.com/logo.svg",
      },
      "details_page": {
        "title": "My Updated Droplet",
        "summary": "A Droplet for my company",
        "logo": "https://my-company.com/big-logo.svg",
        "features": [
          {
            "name": "Feature 1",
            "summary": "Feature 1 summary",
            "details": "Feature 1 details",
            "image_url": "https://my-company.com/new-feature-1.svg"
          },
          {
            "name": "Feature 2",
            "summary": "Feature 2 summary",
            "details": "Feature 2 details",
            "image_url": "https://my-company.com/new-feature-2.svg",
          },
        ]
      }
    }
  }
}

Note: values that are not provided will be assumed to be null.

Listing Companies Using a Droplet

If you are the owner of a Droplet, you can list the companies using that Droplet with a GET request to the /api/droplets/:droplet_uuid/companies endpoint.

curl -i -X GET \
  'https://myco.fluid.app/api/droplets/{uuid}/companies?page=0&per_page=100' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Authenticating as a Company Using a Droplet

A CompanyDroplet represents a company's use of a Droplet. It is created when a Company begins using a Droplet.

You can see the details of a CompanyDroplet for a Droplet your company owns with a GET request to the /api/company_droplets/:uuid endpoint.

curl -i -X GET \
  'https://myco.fluid.app/api/company_droplets/{uuid}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

The most important field in the response is the authentication_token, which can be used to authenticate as the company using the Droplet (it begins with the prefix cdrtkn).

When using the API you can authenticate using the Authorization header with the value Bearer <authentication_token>, e.g. Authorization: Bearer cdrtkn_1234567890.