NAV

topics

Content

Introduction

The rest API provides low level access to the content in a Lingo space.

First off, if you are using javascript, you may want to take a look at LingoJS

You should also get familiar with the types of objects and the data model by reviewing the Glossary

If you find a problem, please open an issue in the GitHub repo.

Authentication

# spaceID="123"
# apiToken="wEJAz9dTsRG-CaE9W0r2vKOpKKZY-l48D6TOAXzDiJE"
"https://$spaceID:$apiToken@api.lingoapp.com/1/kits"

The API uses basic auth to authenticate access to your space.

Requests & Responses

// Success response
{
  "success": true,
  "result": {}
  "server_clock": timestamp
}

// Error response
{
  "success": false,
  "error": {
    "code": 1,
    "message": "An error occured"
  }
  "server_clock": timestamp
}

Every API response includes the same keys at the top level for success and error responses.

Error Codes

{
  unknown: 1,
  serverError: 99,
  invalidParams: 103,
  unauthorized: 401,
  permissionDenied: 403,
  objectNotFound: 404,
  rateLimited: 429,

  kitNotFound: 1100,
  versionNotFound: 1200,
  sectionNotFound: 2100,
  assetNotFound: 3100,
  fileCutUnavailable: 3304,
};

Every lingo error will include one of the codes listed here. Note that most fetches will return a specific error for the type of object being fetched.

Kits

Get all Kits

curl -XGET 'https://123:wEJAz9dTsRG-CaE9W0r2vKOpKKZY-l48D6TOAXzDiJE@api.lingoapp.com/1/kits/'
// Response
{
  "result": {
    "success": true
    "kit": [{
      "kit_uuid": "3BD9CDAF-14DF-495A-AA2F-4993092D62EE",
      "space_id": 5,
      "name": "Brand Kit",
      "status": "active",
      "use_version": 0,
      "date_added": "2017-03-22 05:27:20.152243+0000",
      "date_updated": "2018-04-12 01:19:33.946433+0000",
      "images": {
        "cover": "https://lingo-test.s3.amazonaws.com:443/kits/5/3BD9CDAF-14DF-495A-AA2F-4993092D62EE/cover_1523495973.png"
      }
    },
    { ... }]
  },
  "server_clock": 1548434315
}

GET /1/kits/

Returns a list of all kits in the space

Kit Versions

curl -XGET 'https://123:wEJAz9dTsRG-CaE9W0r2vKOpKKZY-l48D6TOAXzDiJEapi.lingoapp.com/1/kits/3BD9CDAF-14DF-495A-AA2F-4993092D62EE?include=use_versions'
// Response
{
  "result": {
    "success": true
    "kit": {
      "kit_uuid": "3BD9CDAF-14DF-495A-AA2F-4993092D62EE",
      "space_id": 5235,
      "name": "Brand Kit",
      "status": "active",
      "use_version": 0,
      "date_added": "2017-03-22 05:27:20.152243+0000",
      "date_updated": "2018-04-12 01:19:33.946433+0000",
      "versions": [
        {
          "kit_uuid": "3BD9CDAF-14DF-495A-AA2F-4993092D62EE",
          "status": "active",
          "version": 0,
          "version_identifier": "0.0",
          "notes": "",
          "date_added": "2017-03-22 05:27:20.152243+0000",
          "date_updated": "2017-03-22 05:27:20.152243+0000",
          "counts": {
            "assets": 928,
            "items": 952,
            "sections": 8
          }
        }]
    }
  },
  "server_clock": 1548434315
}

GET /1/kits/<kit_id>?include=<options>

Returns a single kit and its versions

Parameters  
idstring - required The uuid of the kit to fetch
includestring Optionally include the versions of the kit. Valid options include versions, use_versions, empty.

Include options

Kit Outline

curl -XGET 'https://123:wEJAz9dTsRG-CaE9W0r2vKOpKKZY-l48D6TOAXzDiJEapi.lingoapp.com/1/kits/3BD9CDAF-14DF-495A-AA2F-4993092D62EE/outline?v=0'
// Response
{
  "result": {
    "success": true
    "kit_version": {
      "kit_uuid": "3BD9CDAF-14DF-495A-AA2F-4993092D62EE",
      "status": "active",
      "version": 0,
      "version_identifier": "0.0",
      "notes": "",
      "date_added": "2017-03-22 05:27:20.152243+0000",
      "date_updated": "2017-03-22 05:27:20.152243+0000",
      "counts": {
        "assets": 125,
        "items": 247,
        "sections": 2
      }
      "sections": [{
          "name": "Brand",
          "uuid": "B1F7A3DD-4E6E-4799-8673-4F857ECC388E",
          "version": 0
          "display_order": 0,
          "headers": [
            {
              "uuid": "D86B229B-0171-4EA3-893D-456760D3E8EF",
              "display_order": -13,
              "name": "Logo",
              "version": 0
            },
            {
              "display_order": 6,
              "name": "Colors",
              "uuid": "B3F207C6-92E4-49AB-9416-44267ADD606E",
              "version": 0
            }
          ]
        },
        {
          "name": "Product",
          "uuid": "237CD43A-B42E-41DC-B00B-E4E88FF7F258",
          "version": 0
          "display_order": 1,
          "headers": [
            {
              "display_order": 22,
              "name": "Images",
              "uuid": "C5EAA76A-C5D7-4986-A4E7-0E4E415FC290",
              "version": 0
            }
          ]
        },
        ]
    }
  },
  "server_clock": 1548434315
}

GET /1/kits/<kit_uuid>/outline/

Retrieve the outline of a kit consisting of a list of sections and the headers within each section.

Parameters  
idstring - required The uuid of the kit to fetch
versioninteger The version of the kit to fetch.

Sections

curl -XGET 'https://123:wEJAz9dTsRG-CaE9W0r2vKOpKKZY-l48D6TOAXzDiJEapi.lingoapp.com/1/sections/B1F7A3DD-4E6E-4799-8673-4F857ECC388E?v=0&page=1&limit=50'

# Response
{
  "success": true,
  "result": {
    "section": {
      "kit_uuid": "3BD9CDAF-14DF-495A-AA2F-4993092D62EE",
      "name": "Brand",
      "status": "active",
      "uuid": "B1F7A3DD-4E6E-4799-8673-4F857ECC388E",
      "version": 0
      "counts": {
        "assets": 62,
        "items": 78
      },
      "creator_id": 4,
      "date_added": "2017-03-22 05:29:13.861927+0000",
      "date_updated": "2017-03-25 19:52:57.525252+0000",
      "display_order": 0,
      "items": [{
          "uuid": "D86B229B-0171-4EA3-893D-456760D3E8EF",
          "kit_uuid": "3BD9CDAF-14DF-495A-AA2F-4993092D62EE",
          "section_uuid": "B1F7A3DD-4E6E-4799-8673-4F857ECC388E",
          "space_id": 5,
          "asset_uuid": null,
          "data": {
            "content": "Logos",
            "display_size": "0"
          },
          "date_added": "2018-01-25 01:30:14.873405+0000",
          "date_updated": "2018-01-25 01:30:14.873405+0000",
          "display_order": -13,
          "status": "active",
          "type": "heading",
          "version": 0
      },
      {
          "uuid": "185DF077-1EC4-48F2-BCE0-62ED41B53D1E",
          "asset_uuid": "9CD0AFF5-B050-4B97-8E65-185F969686D5",
          "kit_uuid": "3BD9CDAF-14DF-495A-AA2F-4993092D62EE",
          "section_uuid": "B1F7A3DD-4E6E-4799-8673-4F857ECC388E",
          "space_id": 5,
          "data": {
            "display_size": "0"
          },
          "date_added": "2018-06-12 18:28:52.131982+0000",
          "date_updated": "2018-11-28 21:24:13.502812+0000",
          "display_order": 0,
          "status": "active",
          "type": "asset",
          "version": 0
          "asset": {
            "type": "SVG",
            "uploader_id": 4,
            "uuid": "9CD0AFF5-B050-4B97-8E65-185F969686D5"
            "colors": [],
            "date_added": "2018-06-12 18:28:52.124741+0000",
            "date_updated": "2018-11-09 20:17:33.254285+0000",
            "dimensions": "192.0x192.0",
            "file_hash": "c8781d12183bb53c2c2c9d3ab4a6f9436acd8784",
            "file_id": "a26f993f-a07e-4c15-8eb5-02b6301028a8",
            "file_updated": "2018-06-12 18:28:52.124741+0000",
            "keywords": "Logo",
            "meta": {},
            "name": "Acme Logo",
            "notes": "",
            "size": 9361,
            "space_id": 5,
            "permalink": "https://api-test.lingoapp.com/v4/assets/9CD0AFF5-B050-4B97-8E65-185F969686D5/download",

            "thumbnail_placeholders": {
                "292": "https://lingo-test.s3.amazonaws.com/thumbnails/placeholder/svg/292x292.png",
                "480": "https://lingo-test.s3.amazonaws.com/thumbnails/placeholder/svg/480x480.png",
                "1232": "https://lingo-test.s3.amazonaws.com/thumbnails/placeholder/svg/1232x1232.png"
            },
            "thumbnails": {
                "292": "https://api-test.lingoapp.com/v4/assets/9CD0AFF5-B050-4B97-8E65-185F969686D5/preview?size=292",
                "480": "https://api-test.lingoapp.com/v4/assets/9CD0AFF5-B050-4B97-8E65-185F969686D5/preview?size=480",
                "1232": "https://api-test.lingoapp.com/v4/assets/9CD0AFF5-B050-4B97-8E65-185F969686D5/preview?size=1232"
            }
          }
        }
      ]
    }
  },
  "server_clock": 1548434315
}

GET /sections/<section_uuid>/

Retrieve the content within each section, paging through items as needed.

Parameters  
section_uuidstring - required The id of the section.
versioninteger The version of the section/kit to fetch (default 0).
pageinteger The page number to retrieve when paging through results.
limitinteger The max number of items to retrieve, up to 200 (default 50).

Assets

Download

curl -XGET 'https://123:wEJAz9dTsRG-CaE9W0r2vKOpKKZY-l48D6TOAXzDiJE@api.lingoapp.com/1/assets/9CD0AFF5-B050-4B97-8E65-185F969686D5/download?type=png'

GET /assets/<asset_id>/download/

Download the file for an asset or one of its available file cuts

Note: The download endpoint is currently rate limited to 2000 every 5 minutes.

Parameters  
assetIdinteger The id of the asset.
typestring The file format to download, or null for the original (default: null).

Available File Cuts

Original Cuts
SVG PNG, PDF, EPS
JPG PNG
PNG JPG
GIF JPG, PNG
EPS PNG
PDF PNG
TIFF PNG, JPG
Sketch SVG, PNG, PDF