Quick Start

Authentication

Before you begin exploring the APIs, you must create a way to authenticate yourself with them. Create an MDM/Insights API Access Token from the "API Access" page in the MDM (see detailed documentation).

Once it is created, you will have to set it in a header on each API request:

Authorization: Bearer <your_api_token>

---

Your "Organization ID/GUID"

API endpoints in Famoco's APIs are scoped to a single organization, so you need to know its ID (for the MDM) or GUID (for Insights) in order to call them.

To do so, call the Organizations endpoint and retrieve them:

GET https://my.famoco.com/api/organizations/
Authorization: Bearer <your_api_token>

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": <your_org_id>,
      "guid": <your_org_guid>,
      "name": "My Organization",
      (...)
    }
  ]
}

---

Documentation

• MDM API documentation
• Insights API documentation

On both instances, you can explore the documentation online or you can also download the OpenAPI schema and open it with an API testing tool.

Example: If using Postman, import the file as a Collection with the following advanced options:

• Naming requests: URL
• Request parameter generation: Schema
• Response parameter generation: Schema
• Folder organization: Tags

Then edit the collection:

• Add your access token in Authorization → Bearer Token : my_token
• Set Variables → baseUrl
  • MDM: https://my.famoco.com
  • Insights: https://insights.famoco.com

---

API Usage Examples

Please check the API Usage Examples page to get inspired!

---

Throttling

API calls are rate-limited to prevent abusive usage which could degrade the performance of the service.

The mechanism limits the number of requests per client for a given time window. Beyond that limit, the API returns an HTTP error (429 Too Many Requests) until the counter is reset, at the end of the time window.

All API requests are limited to a maximum of:

• MDM API endpoints: 100 requests/minute and 1000 requests/hour per client
• MDM API export endpoints (i.e. /api/organizations/<id>/<resource>/export/): 6 requests/minute per client
• Insights API endpoints: 60 requests/minute and 600 requests/hour per client

Note

A client is identified as a user (if authenticated), through an API Access Token, or with their IP address (if it is not authenticated).

Here is a sample response from a request that was rate-limited. The number of seconds to wait before new requests can be sent is given in the Retry-After header.

HTTP 429 Too Many Requests
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Retry-After: 3254
Vary: Accept

{
    "errors": {
        "detail": "Request was throttled. Expected available in 3254 seconds."
    }
}