Skip to main content
API docs by Redocly

Nira HTTP API

Getting Started

Before getting started with Nira's HTTP API, be sure you know your organization's Nira URL prefix (e.g. your-organization.nira.app). Visit the login page if you need any help locating it.

You will also need an API key. To generate one, log in to your Nira organization as an administrator, click the Hamburger menu (Upper left corner), then API Keys → Add. Your API key must be included as the value of the x-api-key HTTP header with every request that you make.

Your API requests should be made to your Nira organization's hostname. For example, if your Nira organization's hostname is your-organization.nira.app, the full request URL to retrieve a list of your user groups would be https://your-organization.nira.app/api/groups

Can't find the API call that you need?

Nira's HTTP API is intentionally simple, as our most requested programmability is exposed in the JavaScript SDK Viewer class. Additional API calls can be added upon request -- simply reach out with a brief description of your use case.

Upload automation

For automation of asset uploads, we typically suggest using our python-based niraclient uploader. If you'd like to implement upload automation using your own code, please reach out with a brief description of your use case and we will provide our low-level upload API documentation.

Enterprise plan required

HTTP API access requires a customized Enterprise plan. Please contact us with any questions.

Software vendor integrations

If you are a software vendor interested in adding Nira upload capabilities into your application, please contact us.

Callout

The callout object represents a Callout in Nira.

The Callout object

uuid
required
string <uuid>

Unique identifier for the callout.

When importing callouts:

  • If the specified uuid matches an existing callout on the asset, the matching callout will be updated with the specified data.
  • If the uuid does not match a callout for the asset, a new callout will be created. The specified uuid will be used for the new callout as long as the uuid isn't already being used by a callout on a different assset. If the uuid is already being used by a callout on a different asset, a new uuid will be used for the new callout.
type
required
string
Default: "CameraBookmark"
Enum: "Annotation" "Defect" "Measurement" "CameraBookmark"

Specifies the type of callout. Measurement callouts are also referred to as Polyline Callouts.

title
string

Title for Annotation and Camera Bookmarks. Also see defectTitle parameter.

content
object

Body content for Annotation callouts.

posX
number <double>

X coordinate for point callouts.

posY
number <double>

Y coordinate for point callouts.

posZ
number <double>

Z coordinate for point callouts.

camPosX
number <double>

Camera position X coordinate.

camPosY
number <double>

Camera position Y coordinate.

camPosZ
number <double>

Camera position Z coordinate.

camTarX
number <double>

Camera target X coordinate.

camTarY
number <double>

Camera target Y coordinate.

camTarZ
number <double>

Camera target Z coordinate.

defectTitle
string

Title used when the callout's type is 'Defect'.

defectDescription
string

Defect description

defectSeverity
integer or null

Numeric value indicating the severity of the defect. 1-5 or null for unknown

defectType
Array of strings

List of defect types associated with the callout.

measurementClosed
boolean

Indicates whether the polyline forms a closed shape. Measurement / polyline callouts only.

measurementLength
number <double>

The calculated sum of all segments of the polyline. Measurement / polyline callouts only. Ignored upon import.

measurementArea
number <double>

The calculated area enclosed by the polyline. Closed measurement / polyline callouts only. Ignored upon import.

points
Array of numbers[ items <double >[ items <double > = 3 items ] ]

An array of ordered 3D points comprising the polyline. Measurement / polyline callouts only.

coordsys
string

The coordinate system used for the callout's 3D positional data (posX/Y/Z, camPosX/Y/Z, camTarX/Y/Z, and points), in EPSG format or 'local' for local coordinates. 'local' can only be used with non-georeferenced assets. For latitude/longitude coordinates, EPSG:4326 should be specified.

Array of objects

A list of photo callouts associated with this callout. Currently, only one photo callout per callout is supported, and they are only applicable to callouts of type Defect.

pdfReportScreenshotId
string <uuid>

Unique identifier of the screenshot image shown for this defect callout in PDF reports. Presence of this attribute implies that this callout was configured to be shown in PDF reports. This attribute is only effective when imported into the same Nira organization from which it was exported.

{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "title": "string",
  • "content": { },
  • "type": "Annotation",
  • "posX": 0.1,
  • "posY": 0.1,
  • "posZ": 0.1,
  • "camPosX": 0.1,
  • "camPosY": 0.1,
  • "camPosZ": 0.1,
  • "camTarX": 0.1,
  • "camTarY": 0.1,
  • "camTarZ": 0.1,
  • "defectTitle": "string",
  • "defectDescription": "string",
  • "defectSeverity": 0,
  • "defectType": [
    • "string"
    ],
  • "measurementClosed": true,
  • "measurementLength": 0.8870510458946228,
  • "measurementArea": 0,
  • "points": [
    • [
      ],
    • [
      ]
    ],
  • "coordsys": "EPSG:4326",
  • "photocallouts": [
    • {
      }
    ],
  • "pdfReportScreenshotId": "78372278-7c24-4f17-acb0-06adfe7460dd"
}

Import callouts for a specific asset

path Parameters
asset_suuid
required
string

The unique identifier for the asset.

query Parameters
removeCalloutsBeforeImport
string
Enum: "1" "0"

Optional parameter to remove existing callouts before import. Can be "1" or "0".

header Parameters
x-api-key
required
string

Your API key

Content-Type
required
string
Enum: "application/json" "text/csv" "text/tab-separated-values"

The content type of the request body. Must be one of 'application/json', 'text/csv', or 'text/tab-separated-values'.

Request Body schema:
required
object

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
{ }

Export callouts for a specific asset

Exports callouts related to the specified asset in the requested format.

path Parameters
asset_suuid
required
string

The unique identifier of the asset.

query Parameters
format
required
string
Enum: "json" "csv" "tsv"

The format of the export. Must be one of 'json', 'csv', or 'tsv'.

coordsys
string
Enum: "local" "asset" "latlong"

The coordinate system that will be used for the exported callouts 3D positional data (posX/Y/Z, camPosX/Y/Z, camTarX/Y/Z, and points). Must be asset, latlong, or local.

  • asset: 3D Positional data will be represented using the coordinate system of the asset. For example, if your asset uses the EPSG:27700 coordinate system, then all 3D positional data will be represented in EPSG:27700. If the asset is not georeferenced, then 3D Positional data will be represented using the coordinate system of the asset's geometry files (i.e. the .obj files).
  • latlong: The X and Y coordinate of all 3D Positional data will be represented using latitude / longitude coordinates, also known as EPSG:4326. Elevation (Z) will be represented using coordinate system of your asset's source files. For example, if the .obj files for the asset use meters to store elevation, then the Z coordinates of the callout positional data will use meters.
  • local: 3D Positional data will be represented using the coordinate system of the asset's geometry files (i.e. the .obj files). This should only be used for non-georeferenced assets. It is almost always better to specify asset instead of local.
include
Array of strings
Default: "pointCallouts,polylineCallouts,photoCallouts,pdfReportScreenshotIds"
Items Enum: "pointCallouts" "polylineCallouts" "photoCallouts" "pdfReportScreenshotIds"
  • pointCallouts Includes 3D point callouts.
  • polylineCallouts Includes 3D polyline / measurement callouts.
  • photoCallouts Includes 2D photo callouts.
  • pdfReportScreenshotIds Preserves Include in PDF Report checkbox options and their associated Screenshot IDs. PDF Report Screenshot IDs are only compatible with your own Nira organization. When importing your callout data into a different Nira organization, the Include in PDF Report checkbox will need to be manually checked for any 3D callouts that you wish to include in PDF reports.
header Parameters
x-api-key
required
string

Your API key

Responses

Response samples

Content type
[
  • {
    • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    • "title": "string",
    • "content": { },
    • "type": "Annotation",
    • "posX": 0.1,
    • "posY": 0.1,
    • "posZ": 0.1,
    • "camPosX": 0.1,
    • "camPosY": 0.1,
    • "camPosZ": 0.1,
    • "camTarX": 0.1,
    • "camTarY": 0.1,
    • "camTarZ": 0.1,
    • "defectTitle": "string",
    • "defectDescription": "string",
    • "defectSeverity": 0,
    • "defectType": [
      ],
    • "measurementClosed": true,
    • "measurementLength": 0.8870510458946228,
    • "measurementArea": 0,
    • "points": [
      ],
    • "coordsys": "EPSG:4326",
    • "photocallouts": [
      ],
    • "pdfReportScreenshotId": "78372278-7c24-4f17-acb0-06adfe7460dd"
    }
]

Asset

The asset object represents an asset in Nira.

Delete an asset

path Parameters
suuid
required
string

Assets's base64 encoded uuid

header Parameters
x-api-key
required
string

Your API key

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "result": {
    • "id": 0,
    • "name": "string",
    • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    • "createdBy": 0,
    • "usesvt": true,
    • "type": "default",
    • "passwordRequired": true,
    • "dccname": "string",
    • "hideBranding": null
    }
}

Change an asset's visibility

This controls whether an asset is publicly accessible or private.

path Parameters
suuid
required
string

Assets's base64 encoded uuid

header Parameters
x-api-key
required
string

Your API key

Request Body schema: application/json
required
visibility
string
Enum: "private" "publicly_accessible"

Responses

Request samples

Content type
application/json
{
  • "visibility": "private"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "result": {
    • "id": 0,
    • "name": "string",
    • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    • "createdBy": 0,
    • "usesvt": true,
    • "type": "default",
    • "passwordRequired": true,
    • "dccname": "string",
    • "hideBranding": null
    }
}

Delete multiple assets

Delete multiple assets that were created prior to a particular point in time. This can be useful for cleaning up older assets.

query Parameters
before
required
string^\d+d?$
Example: before=30d

A timestamp (milliseconds since epoch) or a relative date string in the format "Nd", where N is a positive integer and "d" represents days. For example, "30d" would delete assets created before 30 days ago, and the timestamp "1741201439963" would delete all assets created before 2025-03-05 19:03:59 UTC.

confirm
required
string^(true|false)$
Example: confirm=true

If param is set to 'true', the deletion will be executed.

header Parameters
x-api-key
required
string

Your API key

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "result": [
    • {
      }
    ]
}

Users

Expire all of a user's sessions

Expire all of the login sessions of a user account with the specified email address. Please note, it can take up to 10 minutes after making this request for the user to be forcibly logged out of an ongoing session.

query Parameters
email
required
string
Example: email=example@gmail.com
header Parameters
x-api-key
required
string

Your API key

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "result": [
    • {
      }
    ]
}