# Docs - [Guides](/docs/llms-full.txt): How to do each thing - **Get started** - [Overview](/docs.md): Order 3D models, read the files, render pictures and get told when something changes. One REST API and one key. - [Make your first request](/docs/first-request.md): Create a key, send one product, read it back, subscribe to events and put the viewer on a product page. - [How an integration works](/docs/how-it-works.md): What the API does, how your system and CharpstAR exchange products and files, and what a typical integration looks like. - [Authentication](/docs/authentication.md): How to send your API key with every request, and how keys are made and revoked. - [Errors](/docs/errors.md): The shape of an error answer, every error code, and which errors are safe to retry. - [Limits and request ids](/docs/limits.md): Rate limits, the size and count limits of each call, and the request id to quote when you contact us. - **Keys** - [Create an API key](/docs/keys/create-a-key.md): Make a key for one of your systems in Settings, choose what it may do, and revoke it when you no longer need it. - [What each scope allows](/docs/keys/scopes.md): Which scope a key needs for each call of the API. - **Products and orders** - [Send products](/docs/products/send-products.md): Create or update products by article number, one at a time or in a batch, and read the answer. - [Product data rules](/docs/products/product-rules.md): Which product fields you own and which we own, and what happens when a field changes after modelling has started. - [Read and change products](/docs/products/read-and-change.md): List and read the products we hold for you, change some of their fields, cancel one before modelling starts, and check how much of your range has 3D. - [Import a whole range](/docs/products/import-a-range.md): Load many products from one file, check the file first with a dry run, and read the result of every row. - [Orders](/docs/products/orders.md): List your orders and read one order with the status of each of its items. - [Review and approve models](/docs/products/review.md): Approve a model or send it back to our 3D team with comments, through the API or in your CharpstAR account. - [Status](/docs/products/status.md): What each product status means and how a product moves between them. - [Report a sync run](/docs/products/sync-runs.md): An optional call after each scheduled sync run. - **Assets and the viewer** - [Read your models](/docs/assets/read-your-models.md): Read everything we deliver for one article in one call. - [Read what changed](/docs/assets/what-changed.md): Read several articles in one call, or page through every article that changed since a time. - [Embed the viewer](/docs/assets/embed-the-viewer.md): Show the 3D viewer and AR on your product page with one script and one tag, keyed on the same article number you send us. - **Pictures** - [Start and follow jobs](/docs/pictures/jobs.md): Start packshot, turntable, AI scene, AI edit, scene video and export jobs on your delivered models, and follow them until they finish. - [Presets and styles](/docs/pictures/presets-and-styles.md): List the render presets and scene styles saved for your account, and name them in a job. - [Name files your way](/docs/pictures/file-naming.md): Choose how every image and file we make for you is named, and read or change your naming template. - **Events** - [Listen with webhooks](/docs/events/webhooks.md): Subscribe a URL to signed events, handle retries, catch up after downtime, and manage your subscriptions. - [Check a signature](/docs/events/check-a-signature.md): Verify that an event came from CharpstAR and was not changed on the way, with a complete receiver in Node. - [Event types](/docs/events/event-types.md): Every event we send, when we send it, what its data holds, and an example of each. - **Account** - [Plan and usage](/docs/account/plan-and-usage.md): Read your plan, allowances and usage per kind before you order. - [Support](/docs/support.md): Who to contact, and what to include so we can find the call that failed. - [API reference](/docs/api/llms-full.txt): Every endpoint - [API reference](/docs/api.md): Every call of the API, with its fields, a request you can copy and the answer it gives. - **Keys** - [Check your key](/docs/api/keys/getMe.md): Which company and scopes this key has, and when it expires. Works with any valid key: use it to check that your key works. - **Account** - [Your plan, areas and usage](/docs/api/account/getAccount.md): The account summary an agent reads before it orders: the plan, the areas switched on, what was used in the period and what is left per kind, and this token's own limits. - [Usage by kind and day](/docs/api/account/getUsage.md): Usage by kind and by day for a period. Everything is counted, whether it was ordered through the API, an agent or your CharpstAR account. - **Products** - [Create or update products](/docs/api/products/upsertProducts.md): Create or update products by article number: one product, or { products: [...] } with up to 50. A new article lands in our production team's intake and in your open order; a known one is updated by the ownership rules: before modelling starts every field you own is applied, after that name, category, links, attributes and active still update while a change to dimensionsCm or source3dUrl becomes a change request. A field you leave out keeps its value. Sending the same product again is safe: it answers unchanged and writes nothing. - [List your products](/docs/api/products/listProducts.md): Your products as we hold them, newest first, with their status and order: the products you sent or ordered, and the models we delivered to you by other ways. Filter by status, by whether a model exists, or by changes since a time. - [Read one product](/docs/api/products/getProduct.md): The product as we hold it: your fields, its status, the order it belongs to, and any change waiting for our production team. - [Change some fields of a product](/docs/api/products/patchProduct.md): Change only the fields you send. null clears a field you own. The same ownership rules apply as for POST /api/v1/products: a change to dimensionsCm or source3dUrl after modelling has started becomes a change request. - [Cancel a product before modelling starts](/docs/api/products/cancelProduct.md): Stop a product before modelling starts. Its status becomes cancelled, it leaves our production queue, and status.changed is sent. A product that has started answers 409 not_cancellable; talk to your CharpstAR contact instead. - [Approve a model or request changes](/docs/api/products/reviewProduct.md): When a model has passed our quality check it waits for your approval (review.requested tells you). approve publishes it, exactly as approving in your CharpstAR account does, and asset.approved follows once its files are live; a product with variants is approved with all of them. request_changes sends it back to our 3D team with your comments; each comment can carry an image, which we copy to your account. A model that is not waiting for you answers 409 not_ready. From the third change request on the same model, extra revisions will likely be charged, so that request is made in your CharpstAR account, where you confirm it; the API answers 409 not_ready. Changes to a model that is already delivered are requested the same way: it stays delivered and its links keep working while we make the change, and each one counts against your yearly change allowance (402 allowance_reached once it is used up). - [How much of your range has 3D](/docs/api/products/getCoverage.md): How much of your range has a 3D model: counts in total and per category, and the article numbers without one. The question an agent asks before ordering. - [Report a sync run](/docs/api/products/reportHeartbeat.md): Tell us after each scheduled sync run. Your CharpstAR contact then sees when your system last synced and whether it went well. Optional. - **Orders** - [List your orders](/docs/api/orders/listOrders.md): Your orders, newest first. An order is the batch of products that arrived together, through the API, an import, or your CharpstAR account. - [Read one order with its items](/docs/api/orders/getOrder.md): One order with every item: article, status, delivery date and pending changes. - **Imports** - [Load many products from a file](/docs/api/imports/createImport.md): Load many products from one file, for a first catalogue load or a full refresh. The file is NDJSON (one product per line in the POST /api/v1/products format) or CSV with the same field names in the header row, up to 100,000 products, fetched from an https link. The import runs in the background and applies the same rules as POST /api/v1/products; import.completed is sent when it has finished. With dryRun the whole file is checked and nothing is written. - [How an import is going](/docs/api/imports/getImport.md): Its status, how many rows it has processed and a count for each result. - [The result of every row](/docs/api/imports/getImportResults.md): One line per product, NDJSON, with the same fields as a POST /api/v1/products result plus the row number. Available once the import has finished. - **Assets** - [Read one article](/docs/api/assets/getAsset.md): Everything we deliver for one article: its status, the 3D files, the viewer and AR links, the embed snippet, images and variants. Links are null until the product is delivered. glbUrl and usdzUrl never change for an article; when a model is updated the file behind them changes, and the CDN serves ETag and Last-Modified so you can tell. - [Read many articles, or what changed](/docs/api/assets/listAssets.md): Pass articles (up to 100, comma separated) to read several at once, or since to get every article that changed after that time, oldest change first, 100 a page. With since, keep calling with cursor set to nextCursor until it is null. A product can appear in two runs in a row; write its current state, keyed on articleId. - **Jobs** - [Start one job or a batch](/docs/api/jobs/createJobs.md): Start one job, or up to 50 as { jobs: [...] }. Jobs run our production services on a delivered product: packshot renders, AI scenes, image edits, videos and 3D exports. They queue, and the results are added to the product: new images appear in images[] with the job's id, asset.images.updated is sent, and job.succeeded carries the job with its outputs. A product without a delivered model answers 409 not_ready (edit jobs work on an image and need no model). A batch answers a results array like POST /api/v1/products. Every job type runs. AI jobs (scenes, edits, scene videos) run for an account with an allowance of their kind; without one they answer 403 forbidden. Pictures are made in the order asked, and each is saved under its fileName from the start. An export to a format not switched on for your account answers 403 forbidden. - [List jobs](/docs/api/jobs/listJobs.md): Your jobs, newest first, with their status and outputs. Filter by article, type, status, or changes since a time. - [Read one job](/docs/api/jobs/getJob.md): One job: its status, options as applied, outputs once it succeeded, and the error when it failed. - [Cancel a queued job](/docs/api/jobs/cancelJob.md): Cancel a job while it is queued. A job that has started answers 409 not_cancellable. job.cancelled is sent. Cancelling a cancelled job answers it again. - [Your render presets](/docs/api/jobs/listPresets.md): The render presets of your account: camera, lighting, background, size and format sets our team saved for you. Name one in a packshot job's options.preset. - [Your saved scene styles](/docs/api/jobs/listStyles.md): The saved scene styles of your account, so a whole range shares one look: our team makes them with you. Name one in a scene job's options.style. - **Naming** - [Your naming template](/docs/api/naming/getNaming.md): How files are named for your account, with an example. - [Set your naming template](/docs/api/naming/setNaming.md): Set the naming template for every file we produce for you: the standard pattern, the GS1 Product Image Standard, Amazon's MAIN and PT01 scheme, or your own pattern from the tokens. Override it per job with the job's naming. File names use letters A to Z, digits, '-', '_' and '.', up to 200 characters; accented letters are converted. The same output always gets the same name, so an updated image replaces the earlier file. - **Events** - [Subscribe to events](/docs/api/events/createWebhook.md): Subscribe your https URL to signed events. Up to 3 active subscriptions. The answer carries the signing secret once: store it next to your API key. Leave events out to receive every type, including ones added later. - [List your subscriptions](/docs/api/events/listWebhooks.md): Your subscriptions, newest first, stopped ones included. Secrets are not included. - [Change a subscription](/docs/api/events/patchWebhook.md): Change the URL or the event types of a subscription. - [Stop a subscription](/docs/api/events/deleteWebhook.md): Stop a subscription. Nothing more is sent to it. Safe to repeat. - [Send a test event](/docs/api/events/testWebhook.md): Queue a signed ping event to this subscription. It is sent within about a minute, signed like any other event. - [The last 30 days of deliveries](/docs/api/events/listDeliveries.md): Every delivery of the last 30 days, newest first, with attempts and your receiver's answers. - [Send a delivery again](/docs/api/events/redeliver.md): Send a delivery again, with the same body and the same CharpstAR-Delivery id. - [Issue a new signing secret](/docs/api/events/rotateSecret.md): Issue a new signing secret. The old one stays valid for 24 hours, and every delivery in that time carries a signature for each secret, so you can switch without missing an event. - **Event payloads** - [product.received](/docs/api/event-payloads/product.received.md): A new product is in our intake, whether you sent it or your CharpstAR team added it. data: What we stored: articleId, name, category, subcategory, dimensionsCm, productLink, status and receivedAt. - [status.changed](/docs/api/event-payloads/status.changed.md): A product's status changes, for example from in_production to in_review, or from approved to delivered. Internal steps that keep the same status send nothing. data: from and to, both status values. - [review.requested](/docs/api/event-payloads/review.requested.md): A model has passed our quality check and waits for your approval. data: articleId and a reviewUrl that opens the model in your account. - [asset.approved](/docs/api/event-payloads/asset.approved.md): A model is approved. We hold the event until the files are live (up to 30 minutes), so it usually arrives with status delivered and every link filled in. This is the one to act on. data: The full asset, as in GET /api/v1/assets/{article}. If the files were not live in time, only articleId and status approved; status.changed follows once it is delivered. - [asset.images.updated](/docs/api/event-payloads/asset.images.updated.md): Images were added, replaced or removed for a product. Changes made close together arrive as one event, about a minute later. data: added and removed: image ids. Read the asset again for the images themselves. - [job.succeeded](/docs/api/event-payloads/job.succeeded.md): A job finished and its outputs are on the product. data: The job as it finished, as in GET /api/v1/jobs/{jobId}, outputs included. - [job.failed](/docs/api/event-payloads/job.failed.md): A job could not finish. data: The job as it finished, with error filled in. - [job.cancelled](/docs/api/event-payloads/job.cancelled.md): A job was cancelled: by you while it was queued, or stopped by our team. data: The job, as it was when it was cancelled. - [ping](/docs/api/event-payloads/ping.md): You asked for a test with POST /api/v1/webhooks/{webhook_id}/test. Every subscription gets it; you cannot subscribe to it. data: message. - [Changelog](/docs/changelog/llms-full.txt): What changed, by date - [Changelog](/docs/changelog.md): What changed in the CharpstAR Integration API, newest first, and how versions work. - [Examples](/docs/examples/llms-full.txt): Whole tasks, start to finish - [Examples](/docs/examples.md): Whole tasks from start to finish, with the calls in curl and Node. - [Embed the viewer on a product page](/docs/examples/embed-the-viewer.md): Read an article, paste the viewer snippet into your product template and show the 3D viewer and AR on your shop. - [Sync your catalogue every night](/docs/examples/sync-your-catalogue.md): Send your products in batches or from one file, read what changed since the last run and report the run. - [Render packshots for new articles](/docs/examples/render-packshots.md): List your render presets, start a packshot job for each delivered article and find the pictures on the product. - [Listen for status changes](/docs/examples/listen-for-status-changes.md): Subscribe a URL to signed events, check each signature, run a receiver and use the delivery log when something is missed. - [Approve models from your own tool](/docs/examples/approve-models.md): Receive the review request, show the model to your reviewer and send the verdict back to us. - [Show 3D coverage in your PIM](/docs/examples/coverage-in-your-pim.md): Read how much of your range has a 3D model and list the products that have none yet.