Use the IESDesk API

Send IES and LDT files to IESDesk from your own scripts, and get the same figures, files and jobs as on the pages.

On this page

Status: The API comes with Enterprise. A Free account can use it only in a pilot that IESDesk turns on. The contract can change without notice until the public launch.

Get a token

  1. Make sure that your account has API access. An Enterprise account has it. A Free account has it only when IESDesk turns on the API pilot for the account.
  2. Sign in. Open Account, then API tokens.
  3. Type a name for the token, for example the name of the script that uses it. Type your password. Select Create token.
  4. Copy the token immediately. IESDesk shows it one time only.

An account can have 10 active tokens. A token has no expiry date. A token stops when you revoke it, when the account has neither Enterprise nor the API pilot, when you reset your password, or when the account closes.

A token cannot create or revoke a token. Use the page for that.

Send a request

Send the token in the Authorization header of each request.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" https://iesdesk.com/account
{
  "email_address": "you@example.com", "verified": true, "access_level": "free",
  "file_limits": { "editing": 100, "diagrams": 100, "reports": 100, "bug_rating": 100, "ulor": 100 },
  "api": { "requests_per_minute": 60, "one_file_calls_per_day": 2000, "one_file_calls_today": 0 }
}

one_file_calls_per_day is the daily limit of one-file calls of the account, and one_file_calls_today the calls of today. See "Daily limit of one-file calls".

The account response shows effective file limits. Each accepted job keeps its original limit after an account change. Enterprise report jobs also keep their accepted branding. Free reports use the IESDesk credit and no custom branding.

Every response to a request with a token is JSON. The API ignores the session cookie when the request has a token.

A request with a token and the header Accept: */* (the curl default) also gets JSON on each address of this guide.

Endpoints

Request Result
GET /account The account of the token. Use it to test a token.

The BUG Rating, ULOR, UGR Table, Wall Wash, View, Lighting Scenes, Compare, Report, Generate and Edit services each have their own endpoints. See the section of each service below. Generate answers only for an account with Generate switched on.

BUG Rating service

Rate one file at once, or upload many files and poll a job for one CSV. A file is an IES or an LDT file, 5 MB or less. Free accounts accept 100 files per job. Enterprise defaults to 500; an admin can set a limit up to 2,000.

Rate one file

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F "file=@a.ies" \
  https://iesdesk.com/bug-rating
{ "file_name": "a.ies", "bug_rating": "B1-U0-G1", "b": 1, "u": 0, "g": 1,
  "drivers": { "b": [ "BH", "BM", "BL" ], "u": [], "g": [ "BH" ] },
  "luminaire_lumens": 4614.0,
  "zones": {
    "FL": { "lumens": 607.6, "percent": 13.2 }, "FM": { "lumens": 2360.1, "percent": 51.2 },
    "FH": { "lumens": 620.5, "percent": 13.4 }, "FVH": { "lumens": 7.1, "percent": 0.2 },
    "BL": { "lumens": 325.7, "percent": 7.1 }, "BM": { "lumens": 548.5, "percent": 11.9 },
    "BH": { "lumens": 142.9, "percent": 3.1 }, "BVH": { "lumens": 1.7, "percent": 0.0 },
    "UL": { "lumens": 0.0, "percent": 0.0 }, "UH": { "lumens": 0.0, "percent": 0.0 }
  },
  "flags": [],
  "note": "" }

drivers lists every zone that reaches the rating of its group. The list is empty when the group's rating is 0. A file IESDesk cannot rate answers file_refused with the reason as the message, instead of this shape.

Start a bulk job

Send every file in one request when the whole selection is small. Send groups of at most 100 files and 25 MB for each request when it is large: mark the first group with defer_parse=1, add more groups to the job, then start it.

A small selection, one request:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F "files[]=@a.ies" -F "files[]=@b.ldt" \
  https://iesdesk.com/bug_rating_jobs
{ "id": 42, "state": "queued", "files_count": 2, "url": "https://iesdesk.com/bug_rating_jobs/42" }

A large selection, in groups. The first request:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F defer_parse=1 \
  -F "files[]=@a.ies" -F "files[]=@b.ldt" \
  https://iesdesk.com/bug_rating_jobs
{ "id": 42, "state": "uploading", "files_count": 2,
  "url": "https://iesdesk.com/bug_rating_jobs/42",
  "files_url": "https://iesdesk.com/bug_rating_jobs/42/files",
  "start_url": "https://iesdesk.com/bug_rating_jobs/42/start",
  "files": [
    { "filename": "a.ies", "status": "accepted", "error": null },
    { "filename": "b.ldt", "status": "accepted", "error": null }
  ] }

A refused file (a wrong extension, a file above 5 MB, or a file name that a spreadsheet reads as a formula) still gets a row: its status is "rejected" and error holds the reason. A refused file never stops the other files in its group.

Add a group

Send files_url from the create answer, with the same field name, until the whole selection has arrived:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F "files[]=@c.ies" \
  https://iesdesk.com/bug_rating_jobs/42/files
{ "files": [ { "filename": "c.ies", "status": "accepted", "error": null } ] }

Start the job

Send start_url once every group has arrived:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -X POST \
  https://iesdesk.com/bug_rating_jobs/42/start
{ "id": 42, "state": "queued" }

Poll the job

Poll every 5 seconds until state is "completed" or "failed". files stays empty until the job completes.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  https://iesdesk.com/bug_rating_jobs/42
{ "id": 42, "state": "completed", "files_count": 2, "rated_count": 1, "unrated_count": 1,
  "csv_url": "https://iesdesk.com/bug_rating_jobs/42.csv",
  "files": [
    { "file_name": "a.ies", "bug_rating": "B1-U0-G1", "b": 1, "u": 0, "g": 1,
      "luminaire_lumens": 4614.0, "note": "" },
    { "file_name": "b.ldt", "bug_rating": "N.A.", "b": null, "u": null, "g": null,
      "luminaire_lumens": null, "note": "The document has parse errors." }
  ] }

csv_url is always an IESDesk address, never a Cloudflare R2 address, and it is null until the job completes.

Download the CSV

csv_url needs the same token. It answers the CSV file directly, never a redirect.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -L -o ratings.csv \
  https://iesdesk.com/bug_rating_jobs/42.csv

ULOR service

Calculate the ULOR of one file at once, or upload many files and poll a job for one CSV. A file is an IES or an LDT file, 5 MB or less. Free accounts accept 100 files per job. Enterprise defaults to 500; an admin can set a limit up to 2,000. The values are for the luminaire in the position of the file, with no tilt.

Calculate one file

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" -F "file=@a.ies" https://iesdesk.com/ulor
{ "file_name": "a.ies", "ulor": 2.99, "ulr": 2.99, "dlor": 97.01, "lor": 100.0,
  "upward_lumens": 16.4, "downward_lumens": 532.5, "luminaire_lumens": 548.9, "lamp_lumens": null,
  "absolute_photometry": true, "flags": [ "absolute_photometry" ],
  "note": "The file gives luminaire lumens only. LOR is 100% (EN 13032-4), so ULOR equals ULR." }

Ratios are percents with two decimals. Lumens have one decimal. ulr is the upward flux fraction: the upward lumens divided by the luminaire lumens. lamp_lumens is null for absolute photometry, and then lor is 100.0.

flags holds zero, one, or two values, always in this order:

  • absolute_photometry: the file gives luminaire lumens only. LOR is 100%, so ULOR equals ULR.
  • no_upper_hemisphere_data: the file has no data above 90 degrees, so it declares no upward light.

A file IESDesk cannot read or calculate answers file_refused with the reason as the message. For example, IESDesk does not calculate a file whose negative intensity values give a result below zero.

Start a bulk job

Send every file in one request when the whole selection is small. Send groups when it is large, with at most 100 files and 25 MB for each request. Mark the first group with defer_parse=1, add more groups to the job, then start it.

A small selection, one request:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F "files[]=@a.ies" -F "files[]=@b.ldt" \
  https://iesdesk.com/ulor_jobs
{ "id": 42, "state": "queued", "files_count": 2, "url": "https://iesdesk.com/ulor_jobs/42" }

A large selection, in groups. The first request:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F defer_parse=1 \
  -F "files[]=@a.ies" -F "files[]=@b.ldt" \
  https://iesdesk.com/ulor_jobs
{ "id": 42, "state": "uploading", "files_count": 2,
  "url": "https://iesdesk.com/ulor_jobs/42",
  "files_url": "https://iesdesk.com/ulor_jobs/42/files",
  "start_url": "https://iesdesk.com/ulor_jobs/42/start",
  "files": [
    { "filename": "a.ies", "status": "accepted", "error": null },
    { "filename": "b.ldt", "status": "accepted", "error": null }
  ] }

IESDesk refuses a file with a wrong extension, a file above 5 MB, or a file name that a spreadsheet reads as a formula. A refused file still gets a row: its status is "rejected" and error holds the reason. A refused file never stops the other files in its group.

Add a group

Send files_url from the create answer, with the same field name, until the whole selection has arrived:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F "files[]=@c.ies" \
  https://iesdesk.com/ulor_jobs/42/files
{ "files": [ { "filename": "c.ies", "status": "accepted", "error": null } ] }

Start the job

Send start_url once every group has arrived:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -X POST \
  https://iesdesk.com/ulor_jobs/42/start
{ "id": 42, "state": "queued" }

Poll the job

Poll every 5 seconds until state is "completed" or "failed". files stays empty until the job completes.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  https://iesdesk.com/ulor_jobs/42
{ "id": 42, "state": "completed", "files_count": 2, "calculated_count": 1, "not_calculated_count": 1,
  "csv_url": "https://iesdesk.com/ulor_jobs/42.csv",
  "files": [
    { "file_name": "a.ies", "ulor": 2.99, "ulr": 2.99, "dlor": 97.01, "lor": 100.0,
      "upward_lumens": 16.4, "downward_lumens": 532.5, "luminaire_lumens": 548.9, "lamp_lumens": null,
      "absolute_photometry": true, "flags": [ "absolute_photometry" ],
      "note": "The file gives luminaire lumens only. LOR is 100% (EN 13032-4), so ULOR equals ULR." },
    { "file_name": "b.ldt", "ulor": null, "ulr": null, "dlor": null, "lor": null,
      "upward_lumens": null, "downward_lumens": null, "luminaire_lumens": null, "lamp_lumens": null,
      "absolute_photometry": null, "flags": [], "note": "The document has parse errors." }
  ] }

Each row in files has the same fields and flags values as the answer for one file. A row that IESDesk did not calculate has null numbers, no flags, and the reason in note.

csv_url is always an IESDesk address, never a Cloudflare R2 address, and it is null until the job completes.

Download the CSV

csv_url needs the same token. It answers the CSV file directly, never a redirect.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -L -o ulor.csv \
  https://iesdesk.com/ulor_jobs/42.csv

UGR Table service

Calculate the standard UGR table of one file. A file is an IES or an LDT file, 5 MB or less. This service has no bulk job.

Calculate one file

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" -F "file=@example-linear.ldt" https://iesdesk.com/ugr
{ "file_name": "example-linear.ldt", "flux_basis": 2400.0, "flags": [], "note": "",
  "rows": [
    { "x": 2, "y": 2, "crosswise": [ 18.4, 20.1, 18.8, 20.4, 20.7 ], "endwise": [ 19.5, 21.2, 19.8, 21.5, 21.8 ] },
    { "x": 2, "y": 3, "crosswise": [ 20.0, 21.6, 20.4, 21.9, 22.3 ], "endwise": [ 21.4, 23.0, 21.8, 23.3, 23.6 ] }
  ],
  "source": "Method: CIE 117 / CIE 190; limit: TS EN 12464-1:2021, 5.5.3.2 and Clause 7.",
  "method_claim": "According to CIE 190", "cie_190": true,
  "warnings": [ "This file uses relative photometry. Check the lamp lumens before you use the UGR result." ] }

The example shows the first 2 of the 19 rows, for the Learn example file docs/learn/example-linear.ldt.

  • rows: the 19 standard rooms of CIE 117, in this order: 2H × 2, 3, 4, 6, 8 and 12H; 4H × 2, 3, 4, 6, 8 and 12H; 8H × 4, 6, 8 and 12H; 12H × 4, 6 and 8H. x runs across the line of sight and y along it, in multiples of H, the 2 m from the eye to the luminaire plane.
  • crosswise and endwise: five values each, for the reflectances (ceiling/walls/floor, in percent) 70/50/20, 70/30/20, 50/50/20, 50/30/20 and 30/30/20. Crosswise looks across the luminaire length (C0-C180 plane), endwise along it.
  • Each value has one decimal. A value below 10.0 is a number here; the page shows it as "<10". A room where no luminaire sends light towards the eye gives 0.0. A value is null when the room has no background luminance (flag no_background).
  • flux_basis: the lumens of the table. It is the lamp lumens of the file (the first lamp set of an LDT file, or the lamp lumens times the ballast factor of an IES file), or the luminaire lumens when the file gives no lamp lumens.
  • flags holds zero to three values, always in this order: asymmetric or one_plane_symmetric, then area_out_of_range, then no_background. asymmetric means symmetric about neither main plane; one_plane_symmetric means about one only. note holds the sentence of each flag except no_background.
  • Method: a luminaire that is symmetric about both main planes, and is not a wall washer, an adjustable luminaire, a spotlight or an asymmetric luminaire by its text fields, gets the table of CIE 190:2010 (spacing 1H, mounting height 2 m above the eye, eye height 1.2 m). Any other luminaire gets the CIE 117-1995 tabular method, luminaire spacing 0.25H, eye height 1.2 m, utilisation factors from EN 13032-2:2017 Annex A. With CIE 190, the third reflectance is the reference plane. IESDesk reads an IES file by LM-63-19: the luminaire length runs along 0°.
  • cie_190: true when the table follows CIE 190, else false. method_claim: the line of the page that names the method, "According to CIE 190" or "Calculated with the CIE 117 method.". source: the method and the limit of the page.
  • warnings: the warnings of the page, for example when the file uses relative photometry or the light looks axially symmetric.

A file IESDesk cannot calculate answers file_refused with the reason as the message, for example "The file gives no luminous area, so IESDesk cannot calculate a UGR table."

Wall Wash service

Calculate the light of one ceiling luminaire, or a row of them, on a wall. A file is an IES or an LDT file, 5 MB or less. This service has no bulk job.

Calculate one file

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" -F "file=@example-downlight.ies" -F "height=3" -F "distance=1" -F "count=3" -F "spacing=1" https://iesdesk.com/wall-wash

Fields: unit (m or ft, default m), height (ceiling height, 2 to 20 m or 6.5 to 65 ft, default 3 m or 10 ft), distance (to the wall, 0.1 to 10 m or 0.3 to 33 ft, default 1 m or 3 ft), count (1 to 20, default 1), spacing (0.1 to 20 m or 0.3 to 65 ft, default 1 m or 3 ft, used for 2 or more luminaires). A field that is not sent takes its default; a field that is sent empty is refused. A value out of range answers options_invalid with the range in the message.

{ "file_name": "example-downlight.ies", "unit": "m", "illuminance_unit": "lx",
  "height": 3.0, "distance": 1.0, "count": 3, "spacing": 1.0, "side": null,
  "peak_intensity": { "cd": 850, "c": 0.0, "gamma": 0.0 },
  "brightest": { "value": 304.6, "depth": 0.68 }, "beam_depth": 0.16, "beam_reaches_wall": true,
  "band": 0.45, "average": 184.5, "minimum": 79.9, "uniformity": 0.43, "meets_minimum": true,
  "floor_brightest": { "value": 222.3, "distance": 1.0, "along": 1.0 }, "floor_at_wall": 164.1,
  "note": "Direct light only." }

The example is for the Learn example file docs/learn/example-downlight.ies, a rotationally symmetric downlight, so side is null.

Lengths are in unit. Illuminance is in illuminance_unit. Direct light only: reflections are not in the numbers. The answer has no 3D view.

  • file_name: the name of the uploaded file.
  • unit: m or ft, as sent or the default.
  • illuminance_unit: lx for metres, fc for feet.
  • height: the ceiling height.
  • distance: the distance from the centre of the luminaire to the wall.
  • count: the number of luminaires in the row.
  • spacing: the distance between two luminaires; null for one luminaire.
  • side: the side of the file that faces the wall (C0, C90 and so on for an LDT file, IES 0° and so on for an IES file); null for a rotationally symmetric luminaire, and for a luminaire whose four sides send the same light to the wall (within 0.1 %).
  • peak_intensity.cd: the highest intensity of the file in cd, as a whole number.
  • peak_intensity.c and peak_intensity.gamma: the direction of that intensity in degrees. c is the plane as the file names it: the horizontal angle of an IES file, the C angle of an LDT file.
  • brightest.value: the highest illuminance on the wall.
  • brightest.depth: the depth of that point below the ceiling.
  • beam_depth: the depth where the beam edge (10 % of the downward peak) meets the wall; 0 means at the ceiling; null means the bright part of the beam does not face the wall.
  • beam_reaches_wall: true when the beam edge meets the wall above the floor; null when beam_depth is null.
  • band: the strip at the ceiling and at the floor that average, minimum and uniformity leave out: 0.5 m or 15 % of height, whichever is smaller (EN 12464-1, 5.4); null for one luminaire.
  • average: the average illuminance on the measured part of the wall (between the first and the last luminaire, without a band at the ceiling and the floor, EN 12464-1, 5.4); null for one luminaire.
  • minimum: the lowest illuminance on that part; null for one luminaire.
  • uniformity: minimum divided by average, with two decimals; null for one luminaire, and null when no light reaches the measured part (average 0).
  • meets_minimum: true when uniformity is 0.10 or more (EN 12464-1 minimum for walls); null when uniformity is null.
  • floor_brightest.value: the highest illuminance on the floor in front of the wall, from the wall to one ceiling height behind the luminaires.
  • floor_brightest.distance: the distance of that point from the wall.
  • floor_brightest.along: the distance of that point along the wall from the first luminaire, as the 3D view reads it; null for one luminaire.
  • floor_at_wall: the illuminance on the floor at the foot of the wall, in front of the luminaire, or in front of the middle luminaire of a row (number (n + 1) / 2, rounded down, of the n luminaires that the 3D view shows: the second of 3 or 4, the first of 2). The page names the place of that luminaire along the wall. A long row shows only the luminaires up to about 8 ceiling heights from the first luminaire, so the value never reads above floor_brightest.value.
  • note: always "Direct light only."

A luminaire that sends less than 1 % of its light downward answers file_refused.

A request with a token to /wall-wash always gets this answer, also with the curl default Accept: */*. The Wall scene of Lighting Scenes (POST /lighting-scenes/wall) gives the same figures in the shape of the Lighting Scenes service.

View service

Read one IES or LDT file and get the figures of the Summary card of the IES View and LDT View pages: light output, power, efficacy, peak intensity, the light-emitting area, the symmetry and the catalog fields. A file is an IES or an LDT file, 5 MB or less. This service has no bulk job. It stores nothing.

Read one file

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" -F "file=@example-downlight.ies" https://iesdesk.com/ies/view

POST /ies/view and POST /ldt/view give the same answer. The extension of the file name picks the reader, so each address reads both formats. Send one field, file. A request with a token cannot send the hidden copy of the result page.

{ "status": "read", "file": { "name": "example-downlight.ies", "format": "IES" },
  "title": "Round downlight, 150 mm lens, Example Lighting",
  "figures": { "light_output_lm": 2101.6, "input_power_w": 12.5, "efficacy_lm_per_w": 168.1,
               "peak": { "cd": 850, "c": 0.0, "gamma": 0.0 } },
  "light_emitting_area": { "shape": "Circular", "length": "0.15 m (Diameter)", "width": "0.15 m (Diameter)", "height": "0.00 m" },
  "luminaire_size": null, "symmetry": "Rotational",
  "catalog": [ { "field": "manufac", "name": "[MANUFAC]", "value": "Example Lighting" },
               { "field": "lumcat", "name": "[LUMCAT]", "value": "EX-DL-150" } ],
  "catalog_more": 0, "warnings": [], "warnings_more": 0, "note": null,
  "beam": { "c0_c180": { "toward_c0_deg": 20.0, "toward_c180_deg": 20.0, "beam_angle_deg": 40.0, "peak_gamma_deg": 0.0, "peak_toward": null },
            "c90_c270": { "toward_c90_deg": 20.0, "toward_c270_deg": 20.0, "beam_angle_deg": 40.0, "peak_gamma_deg": 0.0, "peak_toward": null } },
  "beam_notes": [] }

The example is for the Learn example file docs/learn/example-downlight.ies. It shows 2 of the 14 catalog fields.

  • status: always read.
  • file: the name of the uploaded file and its format, IES or LDT.
  • title: the product and the manufacturer of the file, as the Summary card shows them. It is null when the file names neither.
  • figures: the figures of the Summary card. light_output_lm, input_power_w and efficacy_lm_per_w have one decimal. peak.cd is a whole number. peak.c and peak.gamma give the direction of the peak in degrees. A figure that the page cannot print is null.
  • With no intensity table that IESDesk can read, figures holds input_power_w only, and note names the figures that are missing.
  • light_emitting_area: the shape and the sizes of the light-emitting area, in metres, in the words of the Summary card. It is null when the file gives none. A size that cannot print is null.
  • luminaire_size: the shape and the sizes of an LDT luminaire, in the same form. It is null for an IES file.
  • symmetry: the symmetry of the intensity table, in the words of the Summary card.
  • beam: the beam in the C0-C180 and C90-C270 plane pairs, in the planes of the file, lower half only, at 50% of the peak of the pair. toward_c0_deg and toward_c180_deg give the half-intensity edge on each side in degrees from the nadir, with one decimal. An edge below zero lies past the nadir, so the whole beam is on the other side. beam_angle_deg is the sum of the two edges. peak_gamma_deg and peak_toward give the angle of the peak and its side, or null at the nadir. A pair is null when its light never falls to half of the peak; beam is null with no figures.
  • beam_notes: a sentence when the two edges of a pair differ by more than 5 degrees (the beam leans, so the optic is asymmetric), and a sentence when the two pairs differ by more than 5 degrees (the beam is not round). A rotational file has none.
  • catalog: the filled fields that Edit can change, in the order of the file, at most 40. field is the field id, name the name in the file, value the text of the View page. A field that the Summary card shows is not in the list. catalog_more counts the fields after the first 40.
  • warnings: the structure warnings of the file, at most 10. warnings_more counts the others.
  • Each text from the file is UTF-8 and holds at most 200 characters.

The answer has no 3D view, no diagram, no angle and no candela value.

Error Cause
file_missing The request has no file in the field file.
file_refused The View page does not read the name, the extension, the size or the content of the file. The message gives the reasons of the page.

Lighting Scenes service

Calculate the light of one IES or LDT file in one scene of the Lighting Scenes page. A file is an IES or an LDT file, 5 MB or less. This service has no bulk job. It stores nothing.

Calculate one scene

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" -F "file=@example-downlight.ies" -F "height=3" -F "width=6" -F "length=8" \
  https://iesdesk.com/lighting-scenes/room

Send the file in the field file and each setting in its own field. Each scene has its own address:

Address Scene Settings
POST /lighting-scenes/open-area Open area height, width, length, direction
POST /lighting-scenes/street Street height, width, spacing, setback, arm_length, direction, road_surface, wet_surface
POST /lighting-scenes/bollards Bollards height, width, spacing, setback, direction
POST /lighting-scenes/room Room height, suspension, width, length, direction, reflectances
POST /lighting-scenes/room/search Find an even layout height, width, length, mounting_height, plane_height, target_average, required_uniformity, direction, reflectances
POST /lighting-scenes/corridor Corridor height, width, length, spacing, end_distance, direction, reflectances
POST /lighting-scenes/wall Wall height, distance, count, spacing
POST /lighting-scenes/stairs Stairs riser, tread, width, steps, light_every, walls, light_position, direction

On a Street, height is the light-source height and setback the distance from the pole to the road edge. arm_length (0 to 5 m, default 0) reaches from the pole to the light source, so the light source sits arm_length - setback over the road, or behind its edge when that is negative.

  • Every scene also takes unit: m (metres and lux, the default) or ft (feet and foot-candles).
  • The settings have the labels, the limits and the defaults of the form of the scene page. A setting that is not sent takes its default.
  • direction turns the placement: 0, 90, 180 or 270 degrees. The default is 0. The file stays unchanged. Stairs with no direction turns the light by itself: of the four turns, the one that puts the most light on the bottom tread; settings then has no direction.
  • Every scene also takes maintenance_factor: 0.3 to 1, default 0.8. Every light value of the answer is a maintained value: the value of a new installation times the factor (EN 12464-1, ISO/CIE TS 22012). Send 1 for the values of a new installation. A layout search looks for a layout whose maintained average reaches target_average.
  • suspension (Room): from the ceiling down to the luminaire, 0 to 9.7 and shorter than height. Leave it out and IESDesk chooses it from the file: 0.8 m for a file that sends 10 percent or more of its light up, else 0 (on the ceiling). settings gives the value it used.
  • Reflectances (Room, Find an even layout, Corridor): reflectance_ceiling, reflectance_walls and reflectance_floor, whole percent from 0 to 90. The defaults are 70, 50 and 20, or 80, 50 and 20 with standard=ies. The figures of these scenes include the light that the ceiling, the walls and the floor of the empty room reflect (MEMORY 2026-11-20 room-interreflections). Send 0 for all three to get the direct light alone.
  • road_surface (Street): the dry road surface of the road luminance (CIE 144): C1, C2, R1 to R4 or N1 to N4 with standard en, R1 to R4 with ies (ANSI/IES RP-8-25), where a C or N class reads as R3. The default is R3. Another scene ignores it.
  • Every scene also takes standard: en (International, CIE and EN, the default) or ies (North America). It sets the calculation grid, the uniformity measure and the targets, and does not change the unit.
  • lighting_class (Street and Bollards): none (the default) or the key of a class of the chosen standard. With standard=en, a Street takes m1 to m6 (EN 13201-2, Table 1, road luminance) or c0 to c5 (Table 2, illuminance), and Bollards take p1 to p6 (Table 3). With standard=ies, a Street takes major_high, major_medium, major_low, collector_high, collector_medium, collector_low, local_high, local_medium or local_low (ANSI/IES RP-8-25, Table 11-1), and Bollards take walk_high, walk_medium or walk_low (Table 11-2). A class of the other standard reads as none.
  • emergency (Corridor and Open area): 1 checks the emergency lighting, with EN 1838:2024 for standard=en (Corridor: an escape route; Open area: an anti-panic area) or NFPA 101, 7.9.2 for standard=ies (an egress path). emergency_output: the share of the light of the file that the luminaire gives in emergency mode, 1 to 100 percent, default 100. Another scene refuses emergency=1.
  • wet_surface (Street, EN standard): the wet road surface of the wet-road uniformity Uow, W1, W2, W3 or W4 (CIE 144), or none (the default). With standard=ies, or another scene, it reads as none.
  • walls (Stairs): one, between or none. light_position (Stairs): left, right or centre.
  • target_average is in the light unit. required_uniformity is above 0 and at most 1.
{ "status": "calculated", "file": { "name": "example-downlight.ies", "format": "IES" },
  "scene": { "key": "room", "label": "Room" },
  "settings": { "unit": "m", "light_unit": "lx", "height": 3.0, "suspension": 0.0, "width": 6.0, "length": 8.0, "direction": 0,
                "reflectance_ceiling": 70, "reflectance_walls": 50, "reflectance_floor": 20, "maintenance_factor": 0.8 },
  "figures": { "heading": "Floor figures", "minimum": 12.5, "average": 30.5, "direct_average": 25.5, "maximum": 71.8, "uniformity": 0.408 },
  "road": null, "ceiling": null, "end_areas": null, "lowest_tread": null, "layout": null, "wall": null, "warnings": [],
  "notes": [ "Maintained values: the values of a new installation times the maintenance factor of 0.80.",
             "The figures are the values at the points of the EN 12464-1 calculation grid.",
             "Figures include light reflected by the ceiling, walls and floor of an empty room. Furniture and windows are not included.",
             "Obstructions are excluded. The Near field check uses the luminous dimensions in the file. It does not guarantee point-source accuracy. This scene does not assess compliance with a lighting standard." ] }

The example is for the Learn example file docs/learn/example-downlight.ies in the default room.

  • status: calculated for a scene with figures. layout for Find an even layout when it gives a layout with no figures.
  • scene: the key and the label of the scene.
  • settings: the settings that IESDesk used, as numbers, with unit and light_unit (lx or fc).
  • figures: the heading of the figures on the page, then minimum, average and maximum in the light unit with 3 significant digits, and uniformity (minimum / average) with 3 decimals. A Room and a Corridor add direct_average after average: the average of the direct light alone ("Of which direct" on the page). uniformity is null when the scene gets no direct light. A value that the page cannot print is null. figures is null for Wall.
  • road (Street): the road luminance of the dry road, direct light only, in cd/m² in both units. With the EN standard: average (3 significant digits), overall_uniformity (Uo) and longitudinal_uniformity (Ul) with 3 decimals, threshold_increment (TI, in percent, whole numbers, from the luminance of a new installation; EN 13201-3, 8.5), edge_ratio (the edge illumination ratio REI, 3 decimals; EN 13201-3, 8.6) and, with a wet_surface, wet_uniformity (Uow, 3 decimals). With standard=ies: average, average_to_minimum and maximum_to_minimum as texts such as "2.2:1", and veiling_ratio (Lv,max / Lavg, 3 decimals), for the worse travel direction (ANSI/IES RP-8-25). A value that the page cannot print is null. The luminance carries the maintenance factor. Else null.
  • ceiling (Room with a hung luminaire): minimum, average and maximum of the ceiling in the light unit, without the band along the walls, uniformity (minimum / average), and with the EN standard uniformity_check: "passes" for a uniformity of at least 0.10 (EN 12464-1, 5.3.6), else "check in lighting design software". The IES standard gives no verdict: ANSI/IES RP-1 sets no ceiling illuminance. Direct light only. Else null.
  • lighting_class (only when a class was chosen): key, name, source (the table of the standard), title, criteria, status, passes and verdict. Each criterion holds name, value and limit as texts with their unit, bound (at_least or at_most) and passes. status is passes, fails (a road luminance class that does not pass), check (a light level class that direct light alone does not reach: check reflected light in lighting design software), above (the average of a P class is above 1.5 times its value) or unavailable. Else the key is not in the answer.
  • emergency (only with emergency=1): standard (EN 1838:2024 or NFPA 101), kind (escape_route or open_area), title, passes, verdict and reasons (the texts of each reason that it does not pass; empty for NFPA 101). With EN 1838: minimum and required_minimum in the light unit, diversity as a text such as "1:25.0", and glare_within_limit. With NFPA 101: average and minimum in the light unit, and ratio as a text such as "12.0:1". Direct light only. Else the key is not in the answer.
  • end_areas (Corridor): the label, the minimum and the average of each end area. Else null.
  • lowest_tread (Stairs): the index of the tread with the lowest average, counted from the bottom, and its average. Else null.
  • layout (Find an even layout): status (confirmed, no_solution or inconclusive), title, note, target_average, required_uniformity, verdict and arrangement. arrangement holds luminaires, rows, columns, spacing_across, spacing_along, side_wall_distance and end_wall_distance, in the length unit. It is null when the search selected no layout. Else layout is null.
  • wall (Wall): the figures of the Wall Wash service, with the same keys: side, peak_intensity, brightest, beam_depth, beam_reaches_wall, band, average, minimum, uniformity, meets_minimum, floor_brightest and floor_at_wall. Else null.
  • warnings: the warnings of the page for this result.
  • notes: the notes of the page, in the order of the page.

The answer has no 3D view, no display grid, no light value of each point and no geometry. A Room, a Corridor and a layout search include the light that the empty room reflects; the other scenes give direct light only.

Error Cause
options_invalid A setting is not valid. The message gives the texts of the page, for example "Enter road width from 2 to 20 m." IESDesk does not read the file.
file_missing The request has no file in the field file.
file_refused The page does not read the name, the extension or the size of the file. The message gives the reason.
scene_not_calculated IESDesk read the file and has no figures for this scene. The message gives the note of the page, for example the reason that IESDesk cannot read the intensity table.
scene_time_limit The calculation reached its time limit. Reduce the area or try another scene.

Same figures as the page

The View and Lighting Scenes answers give the same figures, texts and refusals as the IES View, LDT View and Lighting Scenes pages and the IESDesk connector for the same file and settings.

Compare service

Compare 2 or 3 IES or LDT files side by side and get the figures of the Figures table of the Compare page. A file is an IES or an LDT file, 5 MB or less. The files can mix IES and LDT. This service has no bulk job.

IESDesk keeps no comparison from the API. For a saved comparison, use the Compare page.

Compare 2 or 3 files

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" -F "files[]=@BE_50593K3.IES" -F "files[]=@BE_50593K3.LDT" https://iesdesk.com/compare

Send each file in the field files[], in the order of the columns. Column 1 is the reference. unit is m (the default) or ft. The unit changes only the sizes of the light-emitting area. A request with a token cannot send the hidden copy of a View result page.

{ "status": "compared", "unit": "m",
  "files": [
    { "position": 1, "name": "BE_50593K3.IES", "format": "IES", "title": "50593K3, BEGA",
      "light_output_lm": 570.6, "light_output_change_percent": null, "input_power_w": 10.0, "input_power_change_percent": null,
      "efficacy_lm_per_w": 57.1, "efficacy_change_percent": null, "peak": { "cd": 641, "c": 0.0, "gamma": 0.0 },
      "beam_angle_c0_c180": 37, "beam_angle_c90_c270": 37, "field_angle_c0_c180": 104, "field_angle_c90_c270": 104,
      "colour_temperature_k": null, "colour_code": null, "downward_share_percent": 92.45, "upward_share_percent": 7.55, "bug_rating": "B1-U2-G0",
      "light_emitting_area": { "shape": "Vertical cylinder", "length": "0.00 m", "width": "0.08 m (Diameter)", "height": "0.02 m" },
      "intensity_note": null },
    { "position": 2, "name": "BE_50593K3.LDT", "format": "LDT", "title": "50593K3, BEGA",
      "light_output_lm": 570.6, "light_output_change_percent": 0, "input_power_w": 10.0, "input_power_change_percent": 0,
      "efficacy_lm_per_w": 57.1, "efficacy_change_percent": 0, "peak": { "cd": 641, "c": 0.0, "gamma": 0.0 },
      "beam_angle_c0_c180": 37, "beam_angle_c90_c270": 37, "field_angle_c0_c180": 104, "field_angle_c90_c270": 104,
      "colour_temperature_k": null, "colour_code": "ww", "downward_share_percent": 92.45, "upward_share_percent": 7.55, "bug_rating": "B1-U2-G0",
      "light_emitting_area": { "shape": "Vertical cylinder", "length": "0.08 m (Diameter)", "width": "0.08 m (Diameter)", "height": "0.02 m" },
      "intensity_note": null } ],
  "warnings": [],
  "notes": [ "Column 1 is the reference. Light output, power and efficacy show the difference to it in percent.",
             "Each file is shown with the angles it stores. US IES files put the front of the luminaire at 0°. LDT files and many IES files made in Europe put it at 90°. So one luminaire can look turned by 90° from one file to another." ] }

The example is for the IES file and the LDT file of the BEGA downlight 50593 (docs/report-service/reference/bega/50593-indoor/international/).

  • status: always compared.
  • unit: m or ft, as sent or the default.
  • files: one entry for each file, in the order of the request.
  • position: the column of the file, from 1. name: the name of the uploaded file. format: IES or LDT.
  • title: the product and the manufacturer of the file, as the Figures table shows them. It is null when the file names neither.
  • light_output_lm, input_power_w and efficacy_lm_per_w have one decimal.
  • light_output_change_percent, input_power_change_percent and efficacy_change_percent: the difference to the file in column 1, in whole percent. They are null for column 1, and when a value or the reference value is missing or zero.
  • peak.cd is a whole number. peak.c and peak.gamma give the direction of the peak in degrees.
  • beam_angle_c0_c180, beam_angle_c90_c270, field_angle_c0_c180 and field_angle_c90_c270: whole degrees in the planes of the file. IESDesk turns no file.
  • colour_temperature_k: the colour temperature that the file states as a number, in kelvin, or null.
  • colour_code: the LDT colour code that the file states, or null: ww (warm white), nw (neutral white), cw (cool white) or dw (daylight white). A file that states a code has no colour_temperature_k, because the code states no number.
  • downward_share_percent and upward_share_percent: the shares of the light output below and above the luminaire, in percent. The Figures table rounds them to two decimals.
  • bug_rating: the BUG rating, for example B1-U2-G0.
  • light_emitting_area: the shape and the sizes of the light-emitting area, in unit, in the words of the Figures table. It is null when the file gives none. A size that cannot print is null.
  • intensity_note: the reason that IESDesk cannot read the intensity table of the file, or null.
  • When IESDesk has no figures for a file, each figure of the file is null, as the Figures table shows "Not in file". A figure that the page cannot print is null too.
  • warnings: the direction warning of the page, when two files may face different directions, then one line "File : " for each intensity note.
  • notes: the notes of the Figures table, in the order of the page.
  • Each text from a file is UTF-8 and holds at most 200 characters.

The answer has no 3D view, no polar curve, no scene, no angle and no candela value. Open the Compare page for the pictures.

Error Cause
file_missing The request has no file in the field files[].
file_refused The request has 1 file or more than 3 files, or the Compare page does not read the name, the extension, the size or the content of a file. The message gives the reasons of the page, each with the file name.

The Compare answer gives the same figures, texts and refusals as the Compare page and the IESDesk connector for the same files.

Report service

Make one PDF report sheet for each file. Upload many files, poll a job, and download one ZIP of PDF files. A file is an IES or an LDT file, 5 MB or less. Free accounts accept 100 files per job. Enterprise defaults to 500; an admin can set a limit from 1 to 2,000.

The one-sheet page /report has no token endpoint. Use a job, even for one file.

Job settings

Send the settings as form fields with the first request of a job. sheet_type is required. The other settings are optional.

Field Values Default
units metric (A4 sheet, metres) or imperial (Letter sheet, feet) metric
sheet_type area (area and road), flood (floodlight) or indoor. Required. none
height The mounting height in the unit of units: from 0.1 to 50 m, or the same range in feet. At most 20 characters. None. The sheet then uses its own height: 4 m or 10 ft, or a 5 m or 15 ft setback on a Floodlight sheet. On a Floodlight sheet with a round beam, the sheet shows the beam at 1 to 5 m (3 to 15 ft) in place of the isolux, and does not use this height.
notify true sends one email when the job ends. Any other value sends no email. No email

IESDesk checks the settings before it makes the job. A setting that is not valid answers options_invalid and makes no job. The message gives the reason. Since 2026-10-04 the API refuses a job with no sheet_type or with auto. A script that sends no sheet_type, or auto, now gets options_invalid.

Start a job

Send every file in one request when the whole selection is small. Send groups when it is large, with at most 100 files and 25 MB for each request. Mark the first group with defer_parse=1, add more groups to the job, then start it.

A small selection, one request:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F "files[]=@a.ies" -F "files[]=@b.ldt" \
  -F units=metric -F sheet_type=area -F height=6 -F notify=true \
  https://iesdesk.com/report_jobs
{ "id": 42, "state": "queued", "files_count": 2, "url": "https://iesdesk.com/report_jobs/42" }

A large selection, in groups. Send the settings with the first request. The first request:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F defer_parse=1 -F units=imperial -F sheet_type=flood \
  -F "files[]=@a.ies" -F "files[]=@b.ldt" \
  https://iesdesk.com/report_jobs
{ "id": 42, "state": "uploading", "files_count": 2,
  "url": "https://iesdesk.com/report_jobs/42",
  "files_url": "https://iesdesk.com/report_jobs/42/files",
  "start_url": "https://iesdesk.com/report_jobs/42/start",
  "files": [
    { "filename": "a.ies", "status": "accepted", "error": null },
    { "filename": "b.ldt", "status": "accepted", "error": null }
  ] }

IESDesk refuses a file with a wrong extension, a file above 5 MB, or a file name that a spreadsheet reads as a formula. A refused file still gets a row: its status is "rejected" and error holds the reason. A refused file never stops the other files in its group.

Add a group

Send files_url from the create answer, with the same field name, until the whole selection has arrived. Do not send the settings again.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F "files[]=@c.ies" \
  https://iesdesk.com/report_jobs/42/files
{ "files": [ { "filename": "c.ies", "status": "accepted", "error": null } ] }

Start the job

Send start_url once every group has arrived:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -X POST \
  https://iesdesk.com/report_jobs/42/start
{ "id": 42, "state": "queued" }

Poll the job

Poll every 5 seconds until state is "completed" or "failed". files stays empty until the job completes.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  https://iesdesk.com/report_jobs/42
{ "id": 42, "state": "completed", "files_count": 2, "sheets_count": 1, "skipped_count": 1,
  "units": "metric", "sheet_type": "area", "mounting_height": "6",
  "zip_url": "https://iesdesk.com/report_jobs/42/download",
  "csv_url": "https://iesdesk.com/report_jobs/42.csv",
  "files": [
    { "file_name": "a.ies", "pdf_file": "a.pdf", "status": "made",
      "sheet_type": "area",
      "luminaire_lumens": 4614.0, "input_watts": 38.0, "efficacy": 121.4,
      "bug_rating": "B1-U0-G1", "road_type": "Type II, Medium", "max_cd": 1520.0, "cie_type": null,
      "note": "" },
    { "file_name": "b.ldt", "pdf_file": null, "status": "skipped",
      "sheet_type": null,
      "luminaire_lumens": null, "input_watts": null, "efficacy": null,
      "bug_rating": null, "road_type": null, "max_cd": null, "cie_type": null,
      "note": "The document has parse errors." }
  ] }

status is "made" when IESDesk made the sheet, or "skipped" when it could not. A skipped row has no PDF, null values, and the reason in note. bug_rating and road_type have a value only on an area and road sheet. cie_type has a value only on an indoor sheet. sheet_type is the type of the job. A job made before 2026-10-04 can show auto as the sheet_type of the job. A job with zero sheets still completes. Its ZIP holds manifest.csv only.

zip_url and csv_url are always IESDesk addresses, never a Cloudflare R2 address. Both are null until the job completes.

Download the ZIP

zip_url needs the same token. It answers with a redirect to a link that expires in 5 minutes, so follow it with -L. curl does not send the token to the second address, and the link needs no token. The ZIP holds one PDF file for each made sheet and manifest.csv. IESDesk keeps the ZIP for 30 days.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -L -o reports.zip \
  https://iesdesk.com/report_jobs/42/download

Download the manifest CSV

csv_url needs the same token. It answers the CSV file directly, never a redirect. It has one row for each file, in upload order.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -L -o manifest.csv \
  https://iesdesk.com/report_jobs/42.csv

Generate

Write one IES or LDT file for each variant of a measured source file. Generate scales the light output of the source by the Multiplier of the variant (EN IEC 62722-2-1:2023 Annex C) and sets the catalog fields from a variant sheet. Each generated file states that it is derived.

An admin switches Generate on for each account. Without the switch, each Generate request answers not_found.

A job has four steps: upload the source files, send the variant sheet, check the match, and start the job. A source file is an IES or an LDT file, 5 MB or less. Free accounts accept 100 source files per job. Enterprise defaults to 500; an admin can set a limit from 1 to 2,000. A variant sheet has at most 10,000 rows; an admin can set a lower limit.

No answer holds a file, an angle or a candela value.

Job settings

Field Values Default
notify true sends one email when the job ends. Any other value sends no email. No email

Upload the source files

Send the files as for the Report service, to https://iesdesk.com/generate_jobs. A job can mix IES and LDT files. A small selection in one request makes a job that waits for its variant sheet:

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F "files[]=@LX-100.ies" -F "files[]=@LX-200.ldt" -F notify=true \
  https://iesdesk.com/generate_jobs
{ "id": 42, "state": "waiting", "files_count": 2, "url": "https://iesdesk.com/generate_jobs/42" }

A large selection goes in groups: mark the first group with defer_parse=1, send the other groups to files_url (https://iesdesk.com/generate_jobs/42/files), then send start_url. Here start_url ends the upload. The job then waits for its variant sheet, and nothing runs yet:

{ "id": 42, "state": "waiting" }

Send the variant sheet

The variant sheet is one CSV file (comma or semicolon, UTF-8) or one Excel file (.xlsx, the first sheet), 5 MB or less, in the field sheet. It has one row for each variant. Headers match without regard to case and surrounding spaces.

Column Required Value
Source yes The key of the source file: its file name without the extension, or its catalog number (see key_choice).
Variant code yes The catalog number of the variant. It is also the name of the output file, with the extension of the source.
Multiplier yes A number above 0. 0.82 and 0,82 both read as 0.82. A value outside 0.5 to 2.0 gives a warning, never a refusal.
Power no The input power in watts. 12.5 and 12,5 both read as 12.5.
Family no The folder of the variant files of the row in the ZIP. Empty puts them at the root. It follows the rules of a folder name: no / \ < > : " | ? *, no control or invisible format character, not . or .., no trailing dot, no name that Windows keeps (for example CON), and at most 200 characters. A Family that breaks a rule gives the row a problem.
Format no The output format of the row: IES, LDT or Both, in any case. Empty follows the output format of the account. A Source ending in .ies or .ldt wins over it. Another value gives the row a problem.
A metadata field no The column header of the metadata sheet download of that format. The editor rules apply. An empty cell keeps the value of the source.

IESDesk checks each cell of a metadata field when it reads the sheet: the number format, the length, control characters and the allowed values. A cell that breaks a rule gives its row a problem, and the problem names the column. A decimal comma reads only in Multiplier and Power.

IESDesk sets the dates, the derived mark and the LDT file name itself. A column for one of these, or for the catalog field or the power field, is ignored with a notice. A column that matches no field is ignored and listed.

A row writes one file for each format of its source. When LX-100.ies and LX-100.ldt share the key, the row LX-100 with the variant code LX-100-830 writes LX-100-830.ies and LX-100-830.ldt. Two source files of one format with the same key make the row a duplicate source, and the row writes no file. Two rows that write the same file name, without regard to case and to the Unicode form (NFC), make the later row a duplicate variant code.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F sheet=@variants.csv \
  https://iesdesk.com/generate_jobs/42/sheet

The answer is the check:

{ "id": 42, "state": "waiting", "key_choice": "file_name",
  "rows_count": 3, "matched_count": 2, "unmatched_count": 1,
  "duplicate_source_count": 0, "duplicate_code_count": 0, "invalid_count": 0, "warning_count": 0, "two_formats_count": 0,
  "variant_file_count": 2,
  "ignored_columns": [ "Colour" ], "notices": [], "unused_sources": [],
  "problems_count": 1,
  "problems": [ { "line": 4, "source": "LX-300", "variant_code": "LX-300-830", "problem": "No source file matches the Source cell." } ],
  "problems_url": "https://iesdesk.com/generate_jobs/42/problems",
  "start_url": "https://iesdesk.com/generate_jobs/42/start" }

The counts count sheet rows. variant_file_count counts the files that the matched rows write. problems holds the first 200 rows with a problem. problems_url gives every row as CSV, with the same token. A second sheet replaces the first while the job waits. IESDesk refuses a sheet that it cannot read, a sheet above 5 MB, and a sheet with no Source, Variant code or Multiplier column with sheet_refused. A request with no file in sheet gets file_missing.

Change the key

key_choice chooses how a row finds its source file. file_name (the default) compares Source with the file name. A Source with no extension matches the IES and the LDT file of that name and writes both (two_formats_count counts these rows, and each gets a problem note); Source ending in .ies or .ldt, in any case, matches only that format. Output files always end in lower-case .ies or .ldt. catalog_number compares it with [LUMCAT] of an IES file or the luminaire number (position 10) of an LDT file.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -X PATCH -F key_choice=catalog_number \
  https://iesdesk.com/generate_jobs/42

The answer is the check of the new match. A key that does not change answers the stored check and matches nothing again. Another value gets options_invalid. The sheet and the key choice share one limit of 20 requests a minute for each account. Above it, a request gets rate_limited with Retry-After: 60.

Start the job

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -X POST \
  https://iesdesk.com/generate_jobs/42/start
{ "id": 42, "state": "queued" }

A job with no matched row gets nothing_matched. While another job of the account uploads, waits in the queue or runs, the start gets job_running. A start of a job that is queued, running, completed or failed answers 200 with { "id": 42, "state": "..." } and changes nothing. After the start, a new sheet or a new key gets job_started. IESDesk deletes the variant sheet file when the job starts. IESDesk deletes a job, with its files, when it waits 24 hours with no change and no start.

Poll the job

Poll every 5 seconds until state is "completed" or "failed".

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  https://iesdesk.com/generate_jobs/42
{ "id": 42, "state": "completed", "files_count": 2, "rows_count": 3, "matched_count": 2,
  "written_count": 2, "failed_count": 0, "key_choice": "file_name",
  "zip_url": "https://iesdesk.com/generate_jobs/42/download",
  "csv_url": "https://iesdesk.com/generate_jobs/42.csv" }

written_count counts the files that IESDesk wrote. failed_count counts the matched variant files that IESDesk did not write. A file can fail its check, or IESDesk can refuse its source file or fail to save it. The result CSV gives the reason. Both counts are null until the job is completed or failed. zip_url and csv_url are always IESDesk addresses, never a Cloudflare R2 address. Both are null until the job completes. zip_url stays null for a completed job without a ZIP.

Download the ZIP

zip_url needs the same token. It answers with a redirect to a link that expires in 5 minutes, so follow it with -L. The ZIP holds one file for each written variant and manifest.csv. IESDesk keeps the ZIP for 30 days.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -L -o variants.zip \
  https://iesdesk.com/generate_jobs/42/download

Download the result CSV

csv_url needs the same token. It answers the CSV file directly. It follows the order of the variant sheet. A matched row gets one CSV row for each file that it wrote or failed to write. Every other row gets one CSV row with an empty Format. The columns are Variant code, Source, Format, Multiplier, Source flux (lm), Variant flux (lm), Power (W), Efficacy (lm/W), Output file, Status, Note, Family and Output format. Family is the Family cell of the row: the ZIP puts the files of the row in a folder of that name. Output format is IES, LDT or BOTH: the formats that the row writes. A skipped row leaves it empty. manifest.csv in the ZIP is the same table.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -L -o variants.csv \
  https://iesdesk.com/generate_jobs/42.csv

Edit service

Upload many IES and LDT files, let IESDesk read them, change their metadata, and download the edited files in one ZIP. The service works as the Edit page: IESDesk makes one batch for each format, and each batch shows in Your files. A file is an IES or an LDT file, 5 MB or less. Free accounts accept 100 files in each batch. Enterprise uses its agreed limit.

IESDesk never changes the photometric data of a file. The export checks each file.

Start a batch

Send every file in one request when the whole selection is small. Send groups when it is large, with at most 100 files and 25 MB for each request. Mark the first group with defer_parse=1, add more groups, then start the read. One request can mix IES and LDT files.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F defer_parse=1 \
  -F "files[]=@BE_50593K3.IES" -F "files[]=@BE_50593K3.LDT" \
  https://iesdesk.com/edit
{ "batch_url": "/edit/uploads/7dKJ9nKek9WyUtwzXdXDH16w",
  "batch_files_url": "/edit/uploads/7dKJ9nKek9WyUtwzXdXDH16w/files",
  "parse_url": "/edit/uploads/7dKJ9nKek9WyUtwzXdXDH16w/parse",
  "accepted_count": 2,
  "files": [
    { "filename": "BE_50593K3.IES", "status": "accepted" },
    { "filename": "BE_50593K3.LDT", "status": "accepted" }
  ],
  "batches": [
    { "batch_id": 101, "format": "IES", "files": 1 },
    { "batch_id": 102, "format": "LDT", "files": 1 }
  ] }

The answer has the status 201. batch_files_url and parse_url are paths on https://iesdesk.com. batch_url is the address of the upload page for a browser. batches has one entry for each format: use batch_id to poll the batch. A refused file gets "status": "rejected" and the reason in error, as in the Report service. A request with no file answers file_missing. When IESDesk refuses every file of the first request, it makes no batch and answers file_refused with the reasons.

Add a group

Send batch_files_url with the same field name until the whole selection has arrived. A group can hold a format that the earlier groups did not have: IESDesk then adds a batch for that format. So batches lists every batch of the upload.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -F defer_parse=1 -F "files[]=@c.ies" \
  https://iesdesk.com/edit/uploads/7dKJ9nKek9WyUtwzXdXDH16w/files
{ "files": [ { "id": 7, "filename": "c.ies", "status": "accepted" } ],
  "batches": [
    { "batch_id": 101, "format": "IES", "files": 2 },
    { "batch_id": 102, "format": "LDT", "files": 1 }
  ] }

Start the read

Send parse_url once every group has arrived. enqueued is the count of files that IESDesk starts to read. A request without defer_parse=1 starts the read at once and needs no parse_url.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -X POST \
  https://iesdesk.com/edit/uploads/7dKJ9nKek9WyUtwzXdXDH16w/parse
{ "enqueued": 3 }

When IESDesk is still writing a group into the batch, the answer is job_running. Wait one second, then send the request again.

Poll the batch

Poll each batch every 5 seconds until state is "editing" or "failed". The states are uploading, parsing, editing, exporting, completed and failed.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  https://iesdesk.com/batches/101
{ "batch_id": 101, "format": "IES", "state": "editing", "read_progress": 100,
  "files": 1, "ready": 1,
  "not_read": [], "not_read_count": 0,
  "refused_on_upload": [], "refused_on_upload_count": 0,
  "fields": [
    { "field": "output_filename", "label": "Output filename", "filled": 1, "examples": ["BE_50593K3.IES"] },
    { "field": "luminaire", "label": "[LUMINAIRE]", "filled": 1, "examples": ["50593K3"] },
    { "field": "manufac", "label": "[MANUFAC]", "filled": 1, "examples": ["BEGA"] }
  ],
  "changes_count": 0, "export": null, "export_failure": null,
  "changes": { "count": 0, "files": 0, "rows": [], "hidden": 0 },
  "saved_at": "2026-10-28T18:54:23.264874Z" }

The example shows 3 of the fields. The keys:

  • read_progress: the percent of the read.
  • files: the files of the batch. ready: the files that an edit can change.
  • not_read: up to 10 files that IESDesk could not read, each with name and reason. not_read_count counts all of them.
  • refused_on_upload: up to 10 files that the upload refused, each with name and reason. refused_on_upload_count counts all of them.
  • fields: each field that an edit can change, in the order of the columns of the Edit page. filled counts the ready files with a value, and examples holds up to 3 values. No field of the photometric data is in the list.
  • changes: the changed values. Each entry of rows holds one change: the file, or the count of files with the same change, field, label, before and after. rows holds at most 50 rows: the rows of many files first, the most files first, then the rows of one file, each in the order of fields. hidden counts the changes that the rows do not show.
  • export: after the export, the count of exported files and up to 10 files that IESDesk did not export, with the reason. Else null.
  • export_failure: the reason when the last export did not finish. Else null.
  • saved_at: the time of the last change of the batch.

A text from a file is at most 200 characters long.

Read the values of a field

Send field with one field of fields, and offset. The answer gives the value of that field in each ready file, 100 files for each request, from offset. next_offset is the offset of the next request, or null after the last file.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  "https://iesdesk.com/batches/101?field=manufac&offset=0"
{ "field": "manufac", "label": "[MANUFAC]", "offset": 0, "next_offset": null,
  "files": [ { "file_id": 7, "name": "BE_50593K3.IES", "value": "BEGA", "cut": false } ] }

cut is true when IESDesk shortened the value for the answer. Do not use a shortened value as a new value. A file in which the edit cannot change this field gets "value": null and "locked": true. A field that is not in fields answers options_invalid.

Change cells

Send the changed cells of a batch in one JSON request, as the Edit page saves them. Each cell names a file (file_id from the values of a field), a field of fields and the new value. Send saved_at from the last answer of the batch.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{ "metadata": { "saved_at": "2026-10-28T18:54:23.264874Z", "operation": "set",
        "cells": [ { "file_id": 7, "field": "manufac", "value": "Bega" },
                   { "file_id": 7, "field": "lumens_per_lamp", "value": "1" } ] } }' \
  https://iesdesk.com/batches/101/metadata
{ "saved_at": "2026-10-28T18:55:02.118402Z",
  "accepted": [
    { "file_id": 7, "field": "manufac", "old_value": "BEGA", "value": "Bega",
      "changed_fields": ["manufac"], "auto_numbered": false, "inserted": false }
  ],
  "rejected": [
    { "file_id": 7, "filename": "BE_50593K3.IES", "field": "lumens_per_lamp", "value": "1",
      "reason": "Field lumens_per_lamp is not editable." }
  ],
  "counts": { "files": 1, "valid": 1, "changed": 1, "renamed": 0, "rejected": 0 },
  "changes": { "count": 1, "files": 1,
    "rows": [ { "files": 1, "file": "BE_50593K3.IES", "field": "manufac", "label": "[MANUFAC]",
                "before": "BEGA", "after": "Bega" } ],
    "hidden": 0 } }

IESDesk checks each value as on the Edit page. A save can change up to 25,000 cells.

  • accepted: each cell that IESDesk saved, with the value before the save in old_value and the saved value in value. A cell that already had the value is in no list. changed_fields lists each changed field of the file. auto_numbered is true when another file of the batch already had the output file name, so IESDesk added a number to the name. inserted is true when the IES file had no line for the field, so the export adds one keyword line.
  • rejected: each cell that IESDesk refused, with the file name in filename, the value that you sent in value, and the reason in reason. The other cells of the save are saved. A field of the photometric data is always refused.
  • changes: every change of the batch, as in "Poll the batch", with the same rows in the same order.
  • saved_at: send it with the next save.

When the saved_at of the request is not the saved_at of the batch, the answer is batch_changed, and IESDesk saves no cell. Read the batch again, then send the save with the new saved_at. When the batch is not open for editing, or the save is not valid, the answer is edit_refused with the reason.

Undo a change

Send "operation": "restore_original" with the cells to put back. Send an empty value. Each cell gets the value of the source file again.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{ "metadata": { "saved_at": "2026-10-28T18:55:02.118402Z", "operation": "restore_original",
        "cells": [ { "file_id": 7, "field": "manufac", "value": "" } ] } }' \
  https://iesdesk.com/batches/101/metadata

The answer has the same shape as a change. Its changes holds the changes that stay, as in "Poll the batch".

Start the export

Start the export when the changes are complete. The export makes one ZIP of the edited files. It needs no Confirm, because the token is the person. A person who uses the Edit page or a chat app presses a button instead.

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -X POST \
  https://iesdesk.com/batches/101/export
{ "state": "exporting" }

The answer has the status 202. IESDesk checks each file before it puts the file in the ZIP, and leaves out each file that fails a check. When the batch is not open for export, or it has no file to export, the answer is edit_refused with the reason. When IESDesk still reads or exports the batch, the answer is job_running.

Poll the export

Poll the batch every 5 seconds until state is "completed", as in "Poll the batch". export then gives the count of exported files and up to 10 files that IESDesk did not export, with the reason. When the export did not finish, state is "editing" again and export_failure gives the reason.

Download the ZIP

curl -H "Authorization: Bearer iesdesk_YOUR_TOKEN" \
  -o batch-101.zip \
  https://iesdesk.com/batches/101/download_export

The ZIP holds each exported file under its output file name, and rejected_files.csv, which lists each file that IESDesk did not export, with the reason. IESDesk keeps the ZIP for 30 days. When the ZIP is not there, the answer is not_found.

Errors

Every error has the same shape: a stable code for the program and a sentence for a person.

{ "error": { "code": "invalid_token", "message": "The API token is not valid or is revoked." } }
Code Status Cause
missing_token 401 The request has no Authorization: Bearer header.
invalid_token 401 The token is not known, or it is revoked.
access_disabled 403 The account has no API access (a Free account with no API pilot), or the account is not verified or is closed.
rate_limited 429 The token sent too many requests, or the address sent too many tokens that are not valid. See "Rate limit".
unverified_email 403 A browser session asked for JSON, and the account has not verified its email address. A token never gets this code.
not_found 404 The resource does not exist, it belongs to another account, or Generate is not switched on for the account. An upload of the Diagrams page has no API, so a token request to it gets this code too. For Edit, the export ZIP of the batch is not there.
file_missing 422 The request has no file in the field the endpoint expects.
file_refused 422 IESDesk could not rate this file; the message gives the reason. For Edit, IESDesk refused every file of the first request, so it made no batch.
too_many_files 422 The job already has, or would have, more files than the file limit of the account for the service. Free accepts 100. Enterprise uses its agreed limit.
job_running 409 The account already has a job uploading or running. Wait until it finishes. For Generate, the start of a waiting job gets it too. For Edit, IESDesk is still writing a group into the batch, or the export finds the batch still read or exported.
options_invalid 422 A job setting or a form setting of a one-file service is not valid, for example a mounting height or a ceiling height outside the range. The message gives the reason. For Edit, the field is not a field that the edit can change.
job_started 422 This job already moved past uploading; send no more groups to it. For Generate: the job already started, so it takes no new sheet and no new key.
sheet_refused 422 IESDesk cannot read or use the variant sheet of a Generate job. The message gives the reason.
nothing_matched 422 No row of the variant sheet of a Generate job matches a source file, so the job cannot start.
daily_limit_reached 429 The account reached its limit of jobs for one day.
api_daily_limit_reached 429 The account reached its daily limit of one-file calls. Retry-After gives the seconds to midnight, Istanbul time. See "Daily limit of one-file calls".
scene_not_calculated 422 Lighting Scenes read the file and has no figures for the scene. The message gives the note of the page.
scene_time_limit 422 The Lighting Scenes calculation reached its time limit.
edit_refused 422 IESDesk did not save the cells of an Edit batch, or did not start its export. For example, the batch is not open for editing, or it has no file to export. The message gives the reason.
batch_changed 409 Another save changed the Edit batch after the saved_at of the request. Read the batch again, then send the save with the new saved_at.

A too_many_files error links to Enterprise in help. A daily_limit_reached or an api_daily_limit_reached error links to Contact.

{ "error": { "code": "too_many_files", "message": "The job has too many files.", "help": "https://iesdesk.com/enterprise" } }

Rate limit

Each token can send 60 requests for each minute. After that, the API answers 429 with the header Retry-After: 60. Wait, then send the request again.

Daily limit of one-file calls

The one-file services share one daily limit for each account: View (IES and LDT), Compare, UGR Table, ULOR, BUG Rating and Lighting Scenes (with Wall Wash). All tokens of the account share it. An Enterprise account starts with 2,000 calls each day; IESDesk can agree another limit with you. GET /account shows the limit and the calls of today.

The day starts at midnight, Istanbul time (UTC+3). Each call counts, also a call that IESDesk refuses because of the file or the settings. A call that the limit of 60 requests each minute refuses does not count.

Above the limit, the API answers 429 with the code api_daily_limit_reached and the header Retry-After, with the seconds to midnight, Istanbul time. The bulk jobs, the account and Edit do not count, and they keep their own limits. The connector in Claude and ChatGPT has its own daily limit of checks.

{ "error": { "code": "api_daily_limit_reached",
  "message": "This account reached its daily limit of one-file API calls. The limit starts again at midnight, Istanbul time (UTC+3).",
  "help": "https://iesdesk.com/contact" } }

One address can send 10 requests with a token that is not valid or is revoked in 3 minutes. After that, the API answers rate_limited with the header Retry-After: 180 to every request with a token that is not valid from that address, until the 3 minutes end. A valid token does not add to this count and always passes, also from that address. Another address has its own count. When a script gets invalid_token, stop it and check the token. Do not send the request again.

Keep the token safe

  • Keep the token out of source control and out of a URL.
  • Use one token for each script or machine. Then you can revoke one token and the others continue to work.
  • Revoke a token immediately when you think that another person has it.