Port Blueprints

Port blueprints

A blueprint is Port's schema primitive. It defines a type of asset in the context lake (a service, a package, a cluster, anything), the properties that describe it, and how it relates to other blueprints. Every entity in Port's context lake is an instance of a blueprint, the same way a database row is an instance of a table schema.

Use this skill when

Use this skill to design or edit a Port data model: creating a new blueprint, adding or typing a property, relating two blueprints, or adding a calculation, mirror, or aggregation property. It is reference-only, built from the static blueprint JSON schema and the raw Port API, so it works without a live Port account or Port MCP server connected. Without credentials it still produces valid blueprint JSON the user can apply later.

Out of scope: workflows (port-workflows), scorecards (port-scorecards), integration mapping (port-integrations), the Terraform/Pulumi provider reference (port-terraform, pointed to in Step 6), and deciding what to model and how blueprints should relate at the data-model-design level (port-context-lake owns that; this skill is the JSON mechanics it points to).

Prerequisites

• Go over the port-getting-started skill first if this is your first time working with Port.
• To apply changes without MCP: a CLIENT_ID/CLIENT_SECRET pair (... menu > Credentials in the Port app), exchanged for a bearer token at POST https://api.port.io/v1/auth/access_token.
• If Port's MCP server is connected, this skill can use it to read the current blueprint (list_blueprints) and apply the result directly (upsert_blueprint) instead of you copying JSON in by hand; the raw API calls below always work as a fallback. Search search_port_knowledge_sources for anything this skill doesn't cover.

Step 1 - Check whether the blueprint already exists

Precondition: you have a bearer token. Action: GET /v1/blueprints/<identifier>. 200 means it exists, edit it instead of duplicating it. 404 means it's safe to create. Fallback: no credentials yet. Draft the JSON and tell the user to verify uniqueness before applying it.

Step 2 - Decide the blueprint's identity

Precondition: you know what real-world asset this blueprint represents. Action: pick an identifier (unique, ≤100 characters, immutable after creation), a human-readable title, and an icon from Port's built-in icon set. Fallback: if the asset isn't precisely named yet, ask, or default to a camelCase noun (microservice, cloudResource) and flag it as a guess.

Step 3 - Define properties

Precondition: you know what data this asset needs to carry. Action: for each field, add a typed entry under schema.properties and, if mandatory, its key to schema.required. See references/property-types.md for the full type system: string, number, boolean, array, object, string formats (url, email, user, team, date-time, timer, yaml, markdown), enum, and meta-properties. Fallback: if the data actually belongs to a different asset, use a relation (Step 4) instead of duplicating it.

Step 4 - Add relations if this asset connects to others

Precondition: entities of this blueprint need to reference entities of another blueprint (ownership, dependency, hierarchy). Action: add a relations entry pointing at the target blueprint's identifier. See references/relations.md for the single vs. many distinction and the required/many constraint. Fallback: if the target blueprint doesn't exist yet, create it first, relations require an existing target.

Step 5 - Add computed properties if useful

Precondition: a value can be derived from this blueprint's own properties, or from related entities, instead of being ingested directly. Action: use a calculation property (JQ over existing properties), a mirror property (pull a value from a related entity), or an aggregation property (count/sum/average across related entities). See references/calculation-properties.md. Fallback: if the source property doesn't exist yet, add it first.

Step 6 - Create or update the blueprint via the API

Precondition: you have a bearer token and a complete blueprint JSON body. Action: use the endpoints below. Prefer PATCH for additive changes to avoid clobbering unrelated fields.

curl -L -X POST 'https://api.port.io/v1/blueprints' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data @blueprint.json

Fallback: a 422 usually means required lists a property that isn't in properties, or a relation target that doesn't exist yet. Fix the JSON and retry, don't silently drop the failing field.

If the user's Port account is managed with Terraform or Pulumi instead of raw API calls, use the port-terraform skill, it owns that reference in depth and the blueprint JSON shape maps directly onto it.

Examples

Ready-to-apply templates:

• assets/basic-service-blueprint.json: a single blueprint, a valid POST /v1/blueprints body, with primitive and formatted string properties.
• assets/blueprint-with-relations.json: a JSON array of two blueprints (team, then microservice), POST them in order, showing a required single relation and a self-referencing many relation.
• assets/blueprint-with-calculation-property.json: a blueprint with a calculation property, a mirror property, and an aggregation property. Assumes a kubernetesCluster and an incident blueprint already exist as relation/aggregation targets.

Common pitfalls

Quick reference

• Blueprint top-level keys: identifier, title, description, icon, schema (properties, required), calculationProperties, mirrorProperties, relations, ownership.
• Property types: string, number, boolean, array, object, plus string formats. Full list: references/property-types.md.
• Relation shape: { "title", "target", "required", "many" }. Details: references/relations.md.
• Derived properties: calculation (JQ), mirror (path into a relation), aggregation (count/sum/average/min/max/median). Details: references/calculation-properties.md.
• Auth: POST /v1/auth/access_token with clientId/clientSecret.