Obtain a Port API token by posting your clientId and clientSecret to https://api.getport.io/v1/auth/access_token and extracting the accessToken from the response.
Define a blueprint in Port (via UI or API) representing the entity type you want to ingest, with identifier, title, and a schema properties object describing each field.
Upsert an entity with POST https://api.getport.io/v1/blueprints/{blueprint_identifier}/entities?upsert=true&merge=true, passing a JSON body with identifier, title, and properties matching the blueprint schema.
To upsert in bulk, loop over your data set and make one POST per entity, or use the Port ocean framework or an official integration for higher-throughput ingestion.
Verify the entity appears in the Port catalog UI under its blueprint and confirm all properties are populated as expected.
Set up relations in the blueprint definition to link entities across blueprints (e.g., linking a Service entity to a Team entity) and populate them in the entity body under the relations key.
Known gotchas
Without upsert=true in the query string, a POST to an existing entity identifier returns an error instead of updating; always include the upsert parameter for idempotent pipelines.
Port property types are strict: passing a string value to a number property causes a validation error rather than a silent coercion, so validate your data types before ingestion.
The accessToken from the auth endpoint expires; implement token refresh logic in long-running ingestion pipelines or the API will start returning 401 errors mid-run.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp