AFRA-CAAC Dismantled Registries — API Guide

This guide explains how to register dismantled aircraft, engines and parts in the AFRA-CAAC Dismantled Registries through the Block Aero External API: how to get an API key, find the records your requests refer to, create and update registry items, search them, and take them through publishing.

A ready-to-run Postman collection accompanies this guide (see Postman collection).

Contents

1. Overview
2. Getting started
3. Before you create items
4. Aircraft registry items
5. Engine registry items
6. Part registry items
7. Updating registry items
8. Searching registry items
9. Publishing and lifecycle
10. Errors
11. Postman collection
12. Reference

Overview

The AFRA-CAAC Dismantled Registries record assets recovered from aircraft disassembly. There are three registries, one per asset type, and items form a hierarchy:

AFRA-CAAC Dismantled Aircraft Registry   (MSN assets)
├── AFRA-CAAC Dismantled Engine Registry (ESN assets)   — optional parent: an aircraft item
│   └── AFRA-CAAC Dismantled Part Registry (PART assets) — parent: an aircraft or engine item
└── AFRA-CAAC Dismantled Part Registry   (PART assets)

Each registry has its own set of endpoints.

You only send what you know; Block Aero attempts to fill in the rest. A create request refers to your asset (and, for aircraft and engines, your certificate), plus the details you would type into the Block Aero app. The platform copies everything else from the referenced records:

• asset details (series, model, serial and part numbers, OEM, country of origin, TSN/CSN, …),
• the certified facility of your certificate,
• the owner's contact email and business address,
• for parts, the removal details of the asset's latest Removal Tag and the most recent operator of the parent item.

Every rule the registries define (required fields, date order, allowed values, …) is checked before anything is saved, and all problems in a request are reported together.

Getting started

Base URL and version

There are 2 primary environments you will interact with. The first is the sandbox environment. This is the first place you should interact with, and where you will do all of your testing. The second is the production environment. This is the environment that your customers and auditors will use to view your records and interact with your registry items.

Sandbox Base URL: https://sandbox.portal.block.aero

Production Base URL: https://portal.block.aero or https://afra.block.aero

All endpoints in this guide are part of External API v2.

Block Aero provides the host name for your environment. Interactive API documentation (Swagger) for your environment is available at https://<your Block Aero environment>/swagger. Select BlockAero API External v2 from the "Select a definition" dropdown at the top right.

Create an API key

API keys are issued per organization and grant only the operations you select.

1. Sign in to Block Aero with a user that can manage API keys.
2. Go to Settings → Organization → API Keys (/app/admin/settings/organization/api-keys) and create a key.
3. Give it a name and an expiration date, and enable the permissions below.
4. Copy the key when it is shown — it is displayed only once and cannot be retrieved later. If you lose it, rotate or create a new key.

Permissions this guide uses:

Keys expire on their expiration date; users who manage API keys are emailed 14 days beforehand. A revoked or expired key stops working immediately.

Authenticate requests

Send the key in the X-Api-Key header on every request:

POST /api/v2/registry-item/afra-caac/aircraft/search?index=0&count=10 HTTP/1.1
Host: <your Block Aero environment>
X-Api-Key: <your API key>
Content-Type: application/json

{}

Response format

Every response is wrapped in the same envelope. The data you asked for is in result:

{
  "result": ["RGI-4f1c2a9e-6b7d-4e8f-9a0b-1c2d3e4f5a6b"],
  "success": true,
  "error": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

On failure success is false and error describes the problem (see Errors).

Conventions

• IDs are 40 characters with a type prefix: ORG- organization, BAA- asset, CRT- certificate, RGI- registry item, REG- registry.
• Dates use ISO 8601, e.g. 2026-09-01T00:00:00Z.
• Dismantling status is sent and stored as a code: "1" Not Started, "2" In-Progress, "3" Complete (see Dismantling status). Responses also include the readable dismantlingStatusLabel.
• Batches: create and update accept an array of 1–100 items. A batch is validated as a whole: if any item is invalid, nothing is saved.

Before you create items

A create request refers to records that must already exist in Block Aero.

1. Your organization ID

GET /api/v2/organization/mine

result.orgId is your organization ID (ORG-…). It is used to filter your assets and certificates below.

2. Your assets

Registry items are created for assets your organization holds a role on. The aircraft registry accepts MSN assets, the engine registry ESN assets and the part registry PART assets.

POST /api/v2/asset/search?index=0&count=20
Content-Type: application/json

{
  "and": [
    { "key": "assetType", "operator": "eq", "value": "MSN" },
    { "key": "roleHolders", "operator": "array_overlap", "values": ["<your orgId>"] },
    { "key": "serialNumber", "operator": "eq", "value": "3456" }
  ]
}

Use the asset's id as assetId. Because asset details are copied into the registry item, make sure the asset record is complete first — for example an aircraft needs its most recent operator, TSN and CSN, unless you provide them in the request.

As in the Block Aero app, an asset can have more than one item in the same registry: creating again for an asset that already has an item makes a second one. To avoid duplicates, search the registry for the asset before creating (see Searching registry items), and if a create times out, check whether it went through before retrying:

{ "key": "assetId", "operator": "eq", "value": "<assetId>" }

3. Your certificate (aircraft and engine)

Aircraft and engine items need the CAAC- or AFRA-issued certificate that authorizes the dismantling project. It must be issued to your organization.

POST /api/v2/certificate/search?index=0&count=20
Content-Type: application/json

{
  "and": [
    { "key": "issuerOrgName", "operator": "in", "values": ["CAAC", "AFRA"] },
    { "key": "recipientOrgId", "operator": "eq", "value": "<your orgId>" }
  ]
}

Use the certificate's id as certificateId. The certificate's facility name and address are copied into the item.

4. The parent item (engine and part)

• An engine may be registered under an aircraft item.
• A part must be registered under an aircraft or engine item.

The parent must have dismantling status "2" (In-Progress) and must not be revoked or expired. Find candidates with the aircraft or engine search:

POST /api/v2/registry-item/afra-caac/aircraft/search?index=0&count=20
Content-Type: application/json

{
  "and": [
    { "key": "metadata.dismantlingStatus", "operator": "eq", "value": "2" },
    { "key": "metadata.asset.serialNumber", "operator": "eq", "value": "3456" }
  ]
}

5. Documents (needed to publish)

When an item is created, the asset's existing documents of the types the registry supports are attached to it automatically. Publishing requires certain documents to be present (see Required documents), so upload them to the asset before creating the item:

POST /api/v2/attach-document
Content-Type: multipart/form-data

file=<the file>
assetIds=BAA-7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f
documentType=coa

Aircraft registry items

POST /api/v2/registry-item/afra-caac/aircraft

[
  {
    "assetId": "BAA-7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "certificateId": "CRT-e5f6a7b8-c9d0-1234-defa-123456789012",
    "dismantlingStatus": "2",
    "projectName": "A320 MSN 3456 Teardown",
    "projectStartDate": "2026-09-01T00:00:00Z",
    "isRemoteProject": false,
    "transferMethodToDismantlingFacility": "ferryFlight",
    "parkingDurationSinceDeregistrationInMonths": 14,
    "parkingDurationAtDismantlingFacilityInMonths": 3,
    "preservationStatusAfterLastFlightRemarks": "Engines inhibited and covered; landing gear pinned.",
    "certificateofAirworthinessNo": "COA-2014-0231",
    "certificateOfDeregistrationNo": "CDR-2026-0117",
    "assetEndOfLifeCertificateNo": "EOLC-2026-0042"
  }
]

Returns the IDs of the created items, in request order:

{ "result": ["RGI-4f1c2a9e-6b7d-4e8f-9a0b-1c2d3e4f5a6b"], "success": true, "error": null }

* Required in the resulting item: if the asset doesn't have a value, you must provide one.

Engine registry items

POST /api/v2/registry-item/afra-caac/engine

[
  {
    "assetId": "BAA-5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e9f",
    "certificateId": "CRT-e5f6a7b8-c9d0-1234-defa-123456789012",
    "parentRegistryItemId": "RGI-4f1c2a9e-6b7d-4e8f-9a0b-1c2d3e4f5a6b",
    "mostRecentOperatorOrgId": "ORG-8ab37c5a-d54a-4ece-9177-382843222cfc",
    "dismantlingStatus": "2",
    "projectName": "CFM56 ESN 577123 Teardown",
    "projectStartDate": "2026-09-01T00:00:00Z",
    "removalDate": "2026-09-10T00:00:00Z",
    "authorizedReleaseCertificateNo": "ARC-2026-00981"
  }
]

* Required in the resulting item: if the asset doesn't have a value, you must provide one.

Part registry items

POST /api/v2/registry-item/afra-caac/part

[
  {
    "assetId": "BAA-99999999-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "parentRegistryItemId": "RGI-2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
    "salesContactEmail": "[email protected]"
  }
]

The removal details (removal date, removal reference, removal tag issuer, certifying staff number and issue date) default to the asset's latest Removal Tag, and the most recent operator is copied from the parent item. Provide any of them to override.

* Required in the resulting item: if neither the asset nor its latest Removal Tag has a value, you must provide one.

Updating registry items

PUT /api/v2/registry-item/afra-caac/{aircraft|engine|part}

Send the item's id and only the fields you want to change. Omitted fields keep their current value; null clears an optional field. The fields that can be updated are the same user-entered fields as on create (asset, certificate and parent can't be changed).

[
  {
    "id": "RGI-4f1c2a9e-6b7d-4e8f-9a0b-1c2d3e4f5a6b",
    "dismantlingStatus": "3",
    "projectEndDate": "2026-12-15T00:00:00Z"
  }
]

Rules:

• The item must belong to the endpoint's registry.
• Your changes are validated together with the rest of the item. You get an error when a field you send is invalid, such as a cleared required field, or when a change makes another field required: setting dismantlingStatus to "3" requires projectEndDate, and setting isRemoteProject to true requires the remote facility fields. A problem already stored on a field you don't send doesn't block the update, so a published item with a missing field can still move through its dismantling statuses.
• Dismantling status can only stay the same or move forward: "1" Not Started → "2" In-Progress → "3" Complete.
• Changing ownerOrgId also refreshes the owner's contact email and address.
• Setting isRemoteProject to false keeps any stored remoteFacilityName and remoteFacilityAddress, as the Block Aero app does, so switching back to true restores them. To remove them, send them as null in the same request.
• After an item is published, only these fields can change:

Searching registry items

POST /api/v2/registry-item/afra-caac/{aircraft|engine|part}/search?index=0&count=100

Returns your organization's items in that registry, with typed metadata. The request body is a search expression; send {} to list everything.

{
  "sort": [{ "column": "updatedBy.timestamp", "direction": "desc" }],
  "and": [
    { "key": "metadata.dismantlingStatus", "operator": "in", "values": ["1", "2"] },
    { "key": "metadata.asset.serialNumber", "operator": "like", "value": "%3456%" }
  ]
}

A search expression is either a single condition (key + operator + value/values) or a group (and / or of expressions), and groups can be nested. sort is only allowed at the top level.

For non-text values add "type": numeric, bool, datetime or uuid, e.g. { "key": "metadata.isLlp", "operator": "eq", "value": "true", "type": "bool" }.

Filter on metadata.dismantlingStatus with the code ("1", "2", "3"), not the label.

Keys use dot notation on the response shape: status, isPublished, assetId, parentRegistryItemId, metadata.<field>, metadata.asset.<field>, createdBy.timestamp, updatedBy.timestamp, and so on.

Response:

{
  "result": {
    "count": 1,
    "items": [
      {
        "id": "RGI-4f1c2a9e-6b7d-4e8f-9a0b-1c2d3e4f5a6b",
        "registryId": "REG-d5ba6480-6c56-4a91-82ad-fd50ff51dda0",
        "assetId": "BAA-7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
        "parentRegistryItemId": null,
        "childRegistryItemIds": [],
        "status": "Draft - Ready",
        "isPublished": false,
        "validityEndDate": null,
        "metadata": {
          "asset": {
            "series": "A320",
            "modelNumber": "A320-214",
            "serialNumber": "3456",
            "aircraftRegNumber": { "value": "EI-DLV" },
            "owner": { "orgId": "ORG-2ae25673-d81b-4de0-817f-9ef5c431e180", "email": "[email protected]" }
          },
          "mostRecentOperatorOrgId": "ORG-8ab37c5a-d54a-4ece-9177-382843222cfc",
          "tsn": 48210,
          "csn": 31877,
          "dismantlingStatus": "2",
          "dismantlingStatusLabel": "In-Progress",
          "projectName": "A320 MSN 3456 Teardown",
          "projectStartDate": "2026-09-01T00:00:00Z",
          "facilityName": "Skytech DFW",
          "amoCertificateNo": "AMO-145-0098"
        },
        "documents": [{ "documentType": "coa" }, { "documentType": "codr" }, { "documentType": "equipmentphoto" }]
      }
    ]
  },
  "success": true
}

(Abbreviated — the full schema is in Swagger.)

Publishing and lifecycle

Statuses

Published items are valid for 730 days and can be renewed.

Required documents

These must be attached to the asset before the item is created (see Documents). documentType values are shown in brackets.

Publish, request review, revoke

Status changes use the generic Registry Items endpoint for all three registries:

PUT /api/v2/registry-item-status?action=publish
Content-Type: application/json

["RGI-4f1c2a9e-6b7d-4e8f-9a0b-1c2d3e4f5a6b"]

action is one of publish, requestReview, revoke, flag, unflag, reflag or revertFlag; which actions you may use depends on your organization's role in the registry. The response lists the IDs whose status changed — an item that can't take the action (for example because it isn't Draft - Ready) is left out rather than causing an error, so compare the result with what you sent.

Parts and engines can only be registered under a parent that is In-Progress; revoking a parent also revokes its children.

Delete

Unpublished items can be deleted:

DELETE /api/v2/registry-item
Content-Type: application/json

["RGI-7d249e91-ff0e-4f5f-a0dc-cd9b37cc21e9"]

• Delete children before parents (part → engine → aircraft), one request per level; an item that still has children can't be deleted.
• Published items are not deleted (they are skipped); revoke them instead.

Errors

A 400 describes every problem found, prefixed with the index of the item in your array:

{
  "success": false,
  "error": {
    "code": 400,
    "message": "The request is invalid: [0] projectStartDate is required when dismantlingStatus is \"2\" (In-Progress) or \"3\" (Complete). [1] assetId BAA-… was not found among your organization's assets.",
    "details": "[0] projectStartDate is required when dismantlingStatus is \"2\" (In-Progress) or \"3\" (Complete).\n[1] assetId BAA-… was not found among your organization's assets."
  }
}

Malformed input (a missing required field, an ID in the wrong format, an empty array) is reported as "Your request is not valid!" with a validationErrors list.

Common messages:

Postman collection

AFRA-CAAC Registry Items.postman_collection.json walks through the whole flow with tests on every response.

1. Import it into Postman.
2. Set the collection variables baseUrl (e.g. https://<your Block Aero environment>) and apiKey.
3. Run the folders in order:

The collection creates real items for your organization; run it against a test environment, or use the cleanup folder afterwards.

Reference

Registries

You never need to send these IDs to the endpoints in this guide; they appear as registryId in responses and are useful when filtering the generic registry-item/search.

Dismantling status

Aircraft and engine items track the dismantling project with dismantlingStatus. Send and filter by the code; responses add the matching dismantlingStatusLabel.

The status can only move forward ("1" → "2" → "3") and stays editable after the item is published. Part items have no dismantling status.

Metadata filled in by Block Aero

Public part lookup

Anyone can check whether a part is registered — no API key needed — with the public lookup used by the QR codes on Removal Tags:

POST /api/v1/caac/search
Content-Type: application/json

{ "PartNumber": "1795M91P01", "SerialNumber": "SN-2019-00437" }

It returns the latest published item from the AFRA-CAAC Dismantled Part Registry. Removal date, removal reference, sales contact, availability and country of origin are left out of the public result.