Skip to content
Craftifact

Artifact lookup API

Reference for resolving existing package artifact IDs from repository-scoped coordinates or exact file attributes.

GET /api/artifacts/search/

Purpose

  • resolve an existing artifact_id before follow-up API calls
  • keep lookups deterministic by combining one repository with exactly one lookup mode
  • return only artifacts visible to the authenticated caller

Request

Query parameters

Always send repository.

Then choose exactly one lookup mode:

Package coordinates

  • Maven: format=maven with name, optional group_id, optional version
  • Python, npm, Go: format with name, optional version

Use this when you know the package coordinates and want the matching artifact ID directly.

Path or filename

  • path
  • filename

Use one of them or both when your automation knows the stored repository path and file name.

Digest

  • digest

Use this when you already have the stored checksum or content digest string for the package artifact.

Validation rules:

  • repository is required
  • group_id only works with format=maven
  • version only works together with name
  • combine repository with exactly one lookup mode
  • limit defaults to 20 and cannot exceed 100
  • offset defaults to 0
Name Required Type
repository Required string
format Optional string · enum: maven, python, npm, go
group_id Optional string
name Optional string
version Optional string
path Optional string
filename Optional string
digest Optional string
limit Optional integer
offset Optional integer

Responses

Common status codes:

  • 200 OK: matching visible artifacts were resolved, or the result set is empty.
  • 400 Bad Request: the query is missing repository, mixes lookup modes, or uses unsupported parameters.
  • 401 Unauthorized: no valid programmatic credentials were provided.
200

OK

Resolved artifact matches visible to the authenticated caller. When no visible artifact matches the lookup, the response still succeeds with an empty results array.
results Required

array

Visible artifacts that matched the requested lookup mode.
total Required

integer

Total number of matches before pagination.
limit Required

integer

Effective result limit applied to the response.
offset Required

integer

Effective result offset applied to the response.
200 Example JSON 
{
  "results": [
    {
      "artifact_id": "4fd75091-2d3a-48b7-9e35-85a5edfa1d92",
      "repository": "libs-release",
      "format": "maven",
      "name": "demo",
      "group_id": "com.example",
      "version": "1.2.3",
      "path": "com/example/demo/1.2.3",
      "filename": "demo-1.2.3.jar"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
400

Bad Request

Bad request. Typical causes include:

  • repository is missing.
  • format is unsupported.
  • group_id was provided outside Maven mode.
  • no lookup mode was selected.
  • multiple lookup modes were combined in one request.
  • limit or offset is invalid.
error Required

string

Human-readable error message for the rejected upload.
400 Example JSON 
{
  "error": "combine repository with exactly one lookup mode"
}
401

Unauthorized

Authentication failed or no programmatic credentials were provided.
error Required

string

Human-readable error message for the rejected upload.
401 Example JSON 
{
  "error": "authentication required"
}

Examples

curl: resolve by Maven coordinates 
curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  "https://packages.example.com/api/artifacts/search/?repository=libs-release&format=maven&group_id=com.example&name=demo&version=1.2.3"
curl: resolve by path 
curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  "https://packages.example.com/api/artifacts/search/?repository=libs-release&path=com/example/demo/1.2.3&filename=demo-1.2.3.jar"