PartGrid.ai
Documentation menu

Parts API

Use PartGrid API v1 to manage company-owned parts and their supported related data from a trusted server-side integration.

Requirements

Use the canonical API host https://api.partgrid.ai and authenticate with a company-scoped bearer API key. Read operations require `parts:read`; mutations require `parts:write`. Every POST, PATCH and DELETE request also requires an `Idempotency-Key` header.

Part endpoints

The Parts API supports listing, creating, retrieving, updating, archiving and restoring company-owned parts. DELETE is a soft archive; hard deletion is not exposed.

GET/v1/parts/
List parts owned by the API-key company.
POST/v1/parts/
Create a part.
GET/v1/parts/{part_id}/
Retrieve a part by UUID.
PATCH/v1/parts/{part_id}/
Update the submitted fields and upsert submitted translations and prices.
DELETE/v1/parts/{part_id}/
Archive a part. Returns 204 when successful.
POST/v1/parts/{part_id}/restore/
Restore an archived part.

List parameters

Name
page
Type
integer
Description
Page number. Defaults to 1.
Name
page_size
Type
integer
Description
Rows per page. Defaults to 25; maximum 100.
Name
include_archived
Type
boolean
Description
Include soft-archived parts in the list. Defaults to false.

Part fields

A part is identified by a stable UUID and a part number. Create requests require `part_number` and the `translations` array defined by the contract. Prices and enabled state are optional.

Writable fields

Name
part_number
Type
string
Description
Part number, maximum 50 characters.
Name
enabled
Type
boolean
Description
Whether the part is enabled.
Name
translations
Type
array
Description
Localized names and optional descriptions. Each item uses a two-letter lowercase language code.
Name
prices
Type
array
Description
Prices using an ISO 4217 three-letter currency code and decimal price value.

Response-only fields

Name
id
Type
UUID
Description
Stable PartGrid API v1 identifier for the part.
Name
archived
Type
boolean
Description
Whether the part is soft-archived.
json
{
  "part_number": "SP-10042",
  "enabled": true,
  "translations": [
    {
      "language": "en",
      "name": "Drive belt",
      "description": "Replacement drive belt"
    }
  ],
  "prices": [
    {
      "currency": "EUR",
      "price": "12.50"
    }
  ]
}
bash
curl --request POST \
  --url 'https://api.partgrid.ai/v1/parts/' \
  --header 'Authorization: Bearer pg_live_example_example' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: part-create-sp-10042-01' \
  --data '{"part_number":"SP-10042","enabled":true,"translations":[{"language":"en","name":"Drive belt"}],"prices":[{"currency":"EUR","price":"12.50"}]}'

Update behavior

PATCH changes only the submitted part fields. Submitted translation languages and price currencies are upserted; translations or prices that are not included in the request are not removed.

Replacement parts

Use replacement endpoints to manage direct replacement relations between active parts owned by the API-key company. Self-references, duplicate relations and cycles are rejected.

GET/v1/parts/{part_id}/replacements/
List direct replacement relations.
POST/v1/parts/{part_id}/replacements/
Add a replacement relation.
PATCH/v1/parts/{part_id}/replacements/{replacement_id}/
Update a replacement relation.
DELETE/v1/parts/{part_id}/replacements/{replacement_id}/
Remove a replacement relation.

Replacement fields

Name
replacement_part_id
Type
UUID
Description
Part to use as the direct replacement.
Name
type
Type
string
Description
`official`, `aftermarket` or `compatible`. Defaults to `official` when creating.
Name
is_preferred
Type
boolean
Description
Mark this relation as preferred. Defaults to false when creating.
Name
notes
Type
string
Description
Optional notes, maximum 5,000 characters.

Part translations

Translations can also be managed one language at a time. Use the translation list endpoint to read current translations and the language-specific endpoint to upsert or remove one translation. The final translation of a part cannot be deleted.

GET/v1/parts/{part_id}/translations/
List translations for a part.
PATCH/v1/parts/{part_id}/translations/{language}/
Create or update one language translation.
DELETE/v1/parts/{part_id}/translations/{language}/
Delete one translation when another translation remains.

Product image

A part can request image ingestion from a public HTTPS source URL. The request is asynchronous: PATCH queues the image, and GET returns its current ingestion status. PartGrid does not expose private storage paths or image bytes through this endpoint.

GET/v1/parts/{part_id}/image/
Retrieve the current product-image ingestion status.
PATCH/v1/parts/{part_id}/image/
Queue an image from a supported public HTTPS source URL. Returns 202 when queued.
DELETE/v1/parts/{part_id}/image/
Delete the product image record.

Errors

Use the HTTP status first, then inspect the JSON response for validation details. Common responses are 400 for invalid data, 401 for invalid credentials, 403 for missing scopes or disabled API access, 404 for unavailable resources, 409 for state or idempotency conflicts, and 429 when the API-key rate limit is exceeded.

Authentication and conventions

See Authentication for credential handling. The API v1 overview will document shared conventions such as idempotency, pagination, rate limits and compatibility.