API Connector

Objective

This guide shows you how to send asset and security-finding data from your own systems into SAFE using the API Connector, so that SAFE can use it for exposure prioritization.

Typical sources are:

• A security data lake such as Databricks, Snowflake or Redshift
• A CMDB or asset inventory you maintain
• Exports from security tools, such as SentinelOne, Tenable or ServiceNow

By the end of this guide you will have:

1. Created API credentials in SAFE and obtained an access token.
2. Exported your data as compressed NDJSON files.
3. Requested secure upload URLs and uploaded your files to SAFE.
4. Confirmed that the data appears on the Assets and Findings pages, labelled with your source name.

Target Users

This document is intended for Engineers and Architects who wish to understand how to post security findings to SAFE. You do not need prior SAFE API experience, but you should be comfortable running curl commands or a short script.

• SAFE Administrator: Creates the API credentials in SAFE and confirms the data after upload.
• Security or Data Engineer: Ingests data from the data lake, builds the NDJSON files, and automates the push.

Prerequisites

On the SAFE side

• SAFE Admin Access
• SAFE API base URL: The URL you use to sign in, for example https://{your-tenant}.safescore.ai
• IP address is allowed: If your tenant restricts access by IP, the machine that calls the SAFE APIs must be on the allowed list

On the Source side

• Read access to data
• A way to export to NDJSON: A query plus a script, notebook or ETL job that writes one JSON object per line. Any language that can write JSON and gzip files works.
• A place to run the push: A server, container or scheduled job with curl or an HTTP client. It must reach your SAFE URL over HTTPS and the upload URLs SAFE returns, which are hosted on Amazon S3
• A secrets manager:  A place to store the API username and password.
• A scheduler (recommended): Pushes should repeat, typically every 24 hours. Use your existing orchestrator or cron.

Data requirements

For every asset you send, make sure your data lake (source) can provide:

1. A source name. The name of the tool the data came from, for example Qualys. It is case-sensitive and appears in SAFE as the asset's source, so keep it identical on every push.
2. At least one identity field. One of cloudResourceId, hostname, fqdn, netbiosName, a MAC address or an IPv4 address. SAFE uses these to match the record to assets it already knows.
3. A complete picture of the asset for that source. Each push replaces what that source previously reported for the asset: findings, software, patches and tags missing from the new record are marked as resolved. Plan to send the full current list every time, not only changes.
4. Open vulnerabilities only. A vulnerability left out of the next push is closed for that source.
5. Everything else (hardware, cloud details, owners, software, patches, compliance results) is optional. Send what you have; more context gives SAFE better prioritization.

Limitations

How it works

You export your data as compressed NDJSON files, ask SAFE for upload URLs, and upload the files over HTTPS. SAFE then matches each asset to the assets it already knows, merges the records, and shows the data on the Assets and Findings pages, labelled with the source name you sent.

Step-by-step procedure

Authenticate

Create API credentials

Skip this if you already have a credential for this feed.

1. In SAFE, go to Settings > API Credentials and select +.
2. Enter a name (for example data-lake-uploader), choose an expiry and select Add.
3. Copy the API Username and Password that SAFE shows and store them in your secrets manager. The password is shown only at creation. The new credential then appears under Settings > API Credentials.

Get an access token

Exchange the credentials for an access token with HTTP Basic authentication:

curl -X POST "https://{your-tenant}.safescore.ai/api/v3/auth" \
  -u "$SAFE_API_USERNAME:$SAFE_API_PASSWORD"

The response contains accessToken, save it.

• A token is valid for 60 minutes. Reuse it for every call in that time instead of authenticating before each call.
• If a SAFE API call returns 401, the token has expired or is invalid. Authenticate again and retry the call once.

Prepare your files

File format

• NDJSON (newline-delimited JSON), UTF-8. Write one asset per line as {"signals":[ {one signal} ]}. Each line is a complete JSON object and lines are separated by \n.
• Do not wrap the lines in an array. Do not put more than one signal in a line's signals array: such a line is skipped.
• gzip-compress every file. The upload URL is signed for application/gzip. Any local file name works; *.ndjson.gz is a useful convention.
• Send each asset once per file, and never split one asset across lines or files.
• Put many assets in each file. Fewer, larger files are better than many small ones. Never send one asset per file.

Example

You only need the fields below to get started. In your file this record is written on one line; it is formatted here for reading.

{
  "signals": [
    {
      "version": "2.0.0",
      "id": "6f1d2c3b-8a4e-4f5a-9b7c-0d1e2f3a4b5c",
      "type": "default",
      "entity": {
        "source": "Qualys",
        "lastSeen": "2026-10-16T18:00:00Z",
        "entityAttributes": {
          "hostname": "WEB-PROD-01",
          "networkInterface": [
            { "ipv4": "10.20.30.40", "macAddress": "0a:1b:2c:3d:4e:5f", "isPrimary": true }
          ]
        }
      },
      "securityContexts": [
        {
          "type": "va",
          "name": "CVE-2024-6387",
          "severity": "high",
          "status": { "complianceStatus": "fail" }
        }
      ]
    }
  ]
}

Record structure

Each line is one signal. version, id, type and entity.source are required, plus at least one identity field. Every other section is optional: send only the sections and fields you have.

Every field, with its format and meaning, is listed in Field reference below.

Optional sections add context: hardware and OS, cloud details, owners, softwares[], patches[] and compensatoryControls[]. Send only what you have. Keys SAFE does not recognise are ignored.

Asset identity: how SAFE recognises a device

Every signal needs at least one identity field: cloudResourceId, hostname / fqdn / netbiosName, networkInterface[].macAddress or networkInterface[].ipv4. SAFE treats two records as the same asset at the first rule that matches:

1. Cloud resource ID is the same (cloudResourceId). Always send it for cloud resources.

2. Host name is the same (hostname, fqdn or netbiosName; not case-sensitive; WEB01 matches WEB01.corp.example.com), and the serial numbers do not differ.

3. MAC address is the same, when one of the two records has no host name. Only the primary interface's IP and MAC (isPrimary, else the first valid one) are used for matching; other interfaces are shown, not matched.

4. IP address is the same, when one of the two records has no host name. The weakest rule: IPs change and public IPs can be shared (NAT), so send private addresses where you can.

Host name and FQDN together. When fqdn contains a dot, SAFE keeps hostname and netbiosName only if they are the same as fqdn; otherwise it keeps the FQDN alone. Matching is not affected (a short name still matches its FQDN), but the short names are not shown. If you have an FQDN, send it in fqdn; send hostname alone only when there is no FQDN.

Skipped records. A record with no usable identity is skipped. Placeholders do not count: 0.0.0.0, 127.0.0.1, 169.254.x.x, IPv6 addresses, 00:00:00:00:00:00, and serials such as N/A. A virtual-machine MAC address (VMware, VirtualBox, Docker and similar) is stored but never used to match. A generic host name such as LINUX, UBUNTU or IPHONE needs a MAC address with it, or the whole record is skipped.

The full-snapshot rule

For each asset and source in a push, SAFE treats the record as the complete, current picture:

• Items in the new signal are added or updated.

• Items SAFE had from that source for that asset, but that are missing from the new signal, are marked as gone (resolved, not deleted). This applies to findings, software, patches, asset tags, location, and compensatory controls (when compensatory-control assessment is enabled for your tenant).

• Assets that are not in the push are not changed.

• Data from other sources on the same asset is not changed.

Always send the full list of findings, software, patches and compensatory controls for an asset, not only what changed since the last push. Send open vulnerabilities only: a vulnerability missing from the source's next signal for that asset is closed.

Source

• entity.source names the tool the data came from, for example Qualys. It is required in every line. A file may contain lines from several sources; each line is processed under its own source.

• Any name is accepted, exactly as you send it. Names are case-sensitive: Qualys and qualys are two different sources. Keep them consistent between pushes.

• A name may be up to 255 characters, must not be only digits, and must not be manual.

• If two tools report the same asset, send each tool's data under its own source name, in its own files or as its own group of rows. SAFE merges them into one asset.

Values

Field reference

Every key is optional unless the Required column says otherwise. Keys not listed here are ignored.

Envelope and entity

Identity, network, location and owners

Hardware and operating system

Send the operating system in hardware, not in softwares. Send agents as softwares.

Cloud

Vulnerabilities

Configuration controls

Software, patches and compensatory controls

Notes:

Each upload URL is signed for one exact file size. So always:

1. Write the NDJSON and gzip it to a file.

2. Read the file's size in bytes from disk (for example os.path.getsize() or stat).

3. Do not re-compress, re-encode or otherwise change a file after measuring it. gzip output changes with the tool, level and timestamp, so a re-compressed file has a different size and S3 refuses the upload.

Request upload URLs

Ask for one upload URL per file, listing the files' sizes in the order you will upload them:

curl -X POST "https://{your-tenant}.safescore.ai/api/v3/integrations/file-ingest/uploads" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"files": [{"sizeBytes": 152340}, {"sizeBytes": 98211}]}'

A successful call returns 201:

{

"success": true,

"data": {

"expiresAt": "2026-10-13T12:59:00Z",

"uploads": [

{

"uploadId": "0b6e…",

"url": "https://….s3.….amazonaws.com/…",

"method": "PUT",

"headers": {

"If-None-Match": "*",

"Content-Type": "application/gzip",

"Content-Length": "152340"

}

}

]
}
}

• uploads is in the same order as files: uploads[0] is for the first file you listed.

• Each upload has an uploadId. Log it with your file name: SAFE support uses it to trace a file. Do not send it back.

• expiresAt is when the URLs stop working, currently just under one hour after the call. Use this value rather than assuming a fixed duration.

• Request URLs only when the files are ready, and only for as many files as you can upload before expiresAt.

Upload the files

Upload each file with an HTTP PUT to its url, sending exactly the headers listed for it and the file as the raw request body:

curl -X PUT "$UPLOAD_URL" \
  -H "If-None-Match: *" \
  -H "Content-Type: application/gzip" \
  --data-binary @assets-part-1.ndjson.gz

An upload URL is a secret. Anyone who has it can upload that one file, once, until it expires, without signing in. It cannot read, list, delete or overwrite anything. Do not log, store or share upload URLs.

What happens after you upload

• A 200 on the upload is your confirmation. There is no separate status API: SAFE validates and processes the file in the background.

• SAFE matches every asset to the assets it already knows (see Asset identity in Step 2) and applies the full-snapshot rule per source.

• Lines that cannot be read, or signals SAFE cannot identify, are skipped; the rest of the file is still processed.

• The data appears on the Assets and Findings pages after processing. In the Asset Source column, data lake sources show the data lake icon; hover over it to see the source name. Use the Asset Source filter to show one source.

Automate the push

A one-off upload loads SAFE once. To keep it current, run the same flow on a schedule.

• Start with one full push, then push regularly. Send every asset once to load SAFE, then push on a schedule, typically once every 24 hours. Each asset you send must still be its full picture.
• Batch your assets. Put many assets in each file and up to 100 files in each push.
• Do not upload the same asset and source twice at once. Processing order for two files that contain the same asset and source is not guaranteed.

APIs used

The integration uses two SAFE APIs and one upload to SAFE storage. Replace https://{your-tenant}.safescore.ai with your SAFE URL.

Best practices

• Start with one full push, then push regularly. Send every asset once to load SAFE, then push changed assets on a schedule, typically once every 24 hours. Each asset you send must still be its full picture.

• Keep each source together. Send each source's assets in as few, full files as possible, and within a file keep each source's rows together rather than mixed. One file per tool is the simplest way.

• Batch assets. Put many assets in each file and up to 100 files in each push. Avoid one asset per file or one push per asset. At the current rate limit a tenant can request 1,000 upload URLs a minute, for example ten pushes of 100 files.

• Do not upload the same asset twice at once. Do not upload two files that contain the same asset and source at the same time: the order in which they are processed is not guaranteed.

• Send identity well. Always send cloudResourceId for cloud resources and macAddress with generic host names. Keep host names stable between pushes; renaming a device can create a second asset.

• Keep source names and finding text stable. Changing a source name creates a new source; rewording the name of a non-CVE finding creates a new finding.

• Validate before uploading. Check that every line is valid JSON, has the envelope fields, entity.source and an identity field, and uses the JSON types in the field reference.

• Handle errors. Re-authenticate once on 401; on 429 wait for Retry-After; on 5xx retry with exponential backoff; do not retry other 4xx errors unchanged.

• Protect secrets. Keep API credentials in a secrets manager and never log access tokens or upload URLs. Log the uploadId and file name instead.

Errors and troubleshooting

Upload URL API : POST /api/v3/integrations/file-ingest/uploads

Did this article help?

Let us know by leaving a star rating at the top of this article.