Back to Top

Skin-tech community

This is the documentation for version 1.0.0 of the API. Last update on Aug 14, 2022.

This API is provided under license Apache, 2.0.

Base URL
https://api.cosmily.com/api/v1

Bearer token (http)

Send a bearer token (“JWT” Formatted) in the Authorization http header to authenticate with the API.


POST /analyze/ingredient_list

POST /analyze/ingredient_list

Returns the analysis of an ingredient list

Body Required
Responses
POST /analyze/ingredient_list
curl \
 -X POST https://api.cosmily.com/api/v1/analyze/ingredient_list \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"ingredients":"string"}'
Request example
{
  "ingredients": "string"
}
Response example (201)
{
  "analysis": {
    "total_ingredients": 42,
    "ingredients_table": [
      {
        "alias": "string",
        "boolean_properties": {
          "acne_fighting": true,
          "aha": true,
          "alcohol": true,
          "allergen": true,
          "anti_aging": true,
          "antioxidant": true,
          "antiseptic": true,
          "bad_for_dry_skin": true,
          "bad_for_oily_skin": true,
          "bad_for_sensitive_skin": true,
          "bha": true,
          "ceramide": true,
          "fragrance": true,
          "fungal_acne_feeding": true,
          "gluten": true,
          "good_for_dry_skin": true,
          "good_for_oily_skin": true,
          "good_for_sensitive_skin": true,
          "healing": true,
          "hyaluronic_acid": true,
          "moisturising": true,
          "niacinamide": true,
          "paraben": true,
          "peg": true,
          "pha": true,
          "retinoid": true,
          "silicone": true,
          "softening": true,
          "soothing": true,
          "sulfate": true,
          "uv_protecting": true,
          "vitamin": true,
          "whitening": true
        },
        "categories": "string",
        "cir_rating": "string",
        "ewg": {
          "background": "string",
          "data": "string",
          "decision": "string",
          "max": 42,
          "min": 42,
          "url": "string"
        },
        "id": 42,
        "index": 42,
        "integer_properties": {
          "comedogenic_rating": 42,
          "natural": 42
        },
        "introtext": "string",
        "title": "string"
      }
    ],
    "harmful": {
      "alcohol": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "allergen": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "comedogenic_rating": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "fragrance": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "fungal_acne_feeding": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "gluten": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "paraben": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "peg": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "silicone": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "sulfate": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      }
    },
    "positive": {
      "acne_fighting": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "anti_aging": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "antioxidant": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "antiseptic": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "healing": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "moisturising": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "softening": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "soothing": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "uv_protecting": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "whitening": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      }
    },
    "notable": {
      "aha": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "antioxidant": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "bha": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "ceramide": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "hyaluronic_acid": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "niacinamide": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "pha": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "retinoid": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "vitamin": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      }
    },
    "ewg": {
      "high": {
        "count": 42,
        "percent": 42.0
      },
      "low": {
        "count": 42,
        "percent": 42.0
      },
      "moderate": {
        "count": 42,
        "percent": 42.0
      },
      "unknown": {
        "count": 42,
        "percent": 42.0
      }
    },
    "natural": {
      "organic": {
        "count": 42,
        "percent": 42.0
      },
      "synthetic": {
        "count": 42,
        "percent": 42.0
      },
      "unknown": {
        "count": 42,
        "percent": 42.0
      }
    },
    "text": "string",
    "description": "string",
    "share_token": "string",
    "owner_user": {
      "id": 42,
      "username": "string"
    },
    "permissions": {
      "can_create_product": true
    }
  }
}

PATCH /analyze/claim/:token

PATCH /analyze/claim/{token}

Marks an unowned ingredient analysis as owned by the logged in user

Path parameters
  • token Required / string(uuid)

    token reference to desired resource

Responses
PATCH /analyze/claim/{token}
curl \
 -X PATCH https://api.cosmily.com/api/v1/analyze/claim/{token} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "result": "claimed",
  "share_token": "string",
  "owner_user": {
    "id": 42,
    "username": "string"
  },
  "permissions": {
    "can_create_product": true
  }
}

GET /analyze/shared/:token

GET /analyze/shared/{token}

Returns a shared ingredient list analysis

Path parameters
  • token Required / string(uuid)

    token reference to desired resource

Responses
GET /analyze/shared/{token}
curl \
 -X GET https://api.cosmily.com/api/v1/analyze/shared/{token} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "analysis": {
    "total_ingredients": 42,
    "ingredients_table": [
      {
        "alias": "string",
        "boolean_properties": {
          "acne_fighting": true,
          "aha": true,
          "alcohol": true,
          "allergen": true,
          "anti_aging": true,
          "antioxidant": true,
          "antiseptic": true,
          "bad_for_dry_skin": true,
          "bad_for_oily_skin": true,
          "bad_for_sensitive_skin": true,
          "bha": true,
          "ceramide": true,
          "fragrance": true,
          "fungal_acne_feeding": true,
          "gluten": true,
          "good_for_dry_skin": true,
          "good_for_oily_skin": true,
          "good_for_sensitive_skin": true,
          "healing": true,
          "hyaluronic_acid": true,
          "moisturising": true,
          "niacinamide": true,
          "paraben": true,
          "peg": true,
          "pha": true,
          "retinoid": true,
          "silicone": true,
          "softening": true,
          "soothing": true,
          "sulfate": true,
          "uv_protecting": true,
          "vitamin": true,
          "whitening": true
        },
        "categories": "string",
        "cir_rating": "string",
        "ewg": {
          "background": "string",
          "data": "string",
          "decision": "string",
          "max": 42,
          "min": 42,
          "url": "string"
        },
        "id": 42,
        "index": 42,
        "integer_properties": {
          "comedogenic_rating": 42,
          "natural": 42
        },
        "introtext": "string",
        "title": "string"
      }
    ],
    "harmful": {
      "alcohol": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "allergen": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "comedogenic_rating": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "fragrance": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "fungal_acne_feeding": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "gluten": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "paraben": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "peg": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "silicone": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      },
      "sulfate": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "slug": "string",
        "title": "string"
      }
    },
    "positive": {
      "acne_fighting": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "anti_aging": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "antioxidant": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "antiseptic": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "healing": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "moisturising": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "softening": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "soothing": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "uv_protecting": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "whitening": {
        "count": 42,
        "description": "string",
        "image_url": "string",
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      }
    },
    "notable": {
      "aha": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "antioxidant": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "bha": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "ceramide": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "hyaluronic_acid": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "niacinamide": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "pha": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "retinoid": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      },
      "vitamin": {
        "count": 42,
        "list": [
          {
            "index": 42,
            "title": "string",
            "alias": "string"
          }
        ],
        "title": "string"
      }
    },
    "ewg": {
      "high": {
        "count": 42,
        "percent": 42.0
      },
      "low": {
        "count": 42,
        "percent": 42.0
      },
      "moderate": {
        "count": 42,
        "percent": 42.0
      },
      "unknown": {
        "count": 42,
        "percent": 42.0
      }
    },
    "natural": {
      "organic": {
        "count": 42,
        "percent": 42.0
      },
      "synthetic": {
        "count": 42,
        "percent": 42.0
      },
      "unknown": {
        "count": 42,
        "percent": 42.0
      }
    },
    "text": "string",
    "description": "string",
    "share_token": "string",
    "owner_user": {
      "id": 42,
      "username": "string"
    },
    "permissions": {
      "can_create_product": true
    }
  }
}

GET /analyze/:token/ingredient_feelings

GET /analyze/{token}/ingredient_feelings

Returns feelings for each ingredient with feelings

Path parameters
  • token Required / string(uuid)

    token reference to desired resource

Responses
GET /analyze/{token}/ingredient_feelings
curl \
 -X GET https://api.cosmily.com/api/v1/analyze/{token}/ingredient_feelings \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "data": [
    {
      "id": 42,
      "active": true,
      "feeling_type": "positive",
      "created_at": "string",
      "updated_at": "string",
      "ingredient_id": 42,
      "author_user_id": 42,
      "author_user": {
        "id": 42,
        "username": "string",
        "user_type": "string",
        "last_active": "string"
      }
    }
  ]
}

GET /analyze/:token/similar_products

GET /analyze/{token}/similar_products

Returns products similar to the ingredient list analysis

Path parameters
  • token Required / string(uuid)

    token reference to desired resource

Responses
GET /analyze/{token}/similar_products
curl \
 -X GET https://api.cosmily.com/api/v1/analyze/{token}/similar_products \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "similar": [
    {
      "product_id": 42,
      "category_id": 42,
      "score": 42,
      "percent_match": 42
    }
  ]
}

POST /analyze/effects

POST /analyze/effects

Returns the positive, harmful, and notable effects for the submitted list of ingredients

Body Required
Responses