---
title: "Add a reference to another project"
method: POST
path: "/projects/{projectId}/references"
tags: ["Projects", "Preview"]
---

# Add a reference to another project

`POST /projects/{projectId}/references`

## Request

- Base URL: `https://app.ketryx.com/api/v1`
- URL: `https://app.ketryx.com/api/v1/projects/{projectId}/references`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ketryx/apis/ketryx-api/docs/projects/:projectId/references/post.ts> (a function with typed inputs; its response is checked against the schema)

Adds a cross-project reference from this project (the referencing project, e.g. a product) to another project in the organization (the referenced project, e.g. a service it uses), the same way "Add referenced project" on the References page does. By default the referencing project can link to the referenced items but does not incorporate them. Safe to repeat: if the reference already exists, nothing is changed and the response has status already_exists with the current settings.

## Path parameters

- `projectId` string, required: Ketryx ID of the referencing project, e.g. the product that uses a service

## Request body

- object
  - `referencedProjectId` string, required: Ketryx ID of the referenced project, e.g. the service or library the referencing project uses
  - `incorporateItems` boolean: Whether all items of the referenced project are also shown in the referencing project (incorporated items filter "*"). Defaults to false: reference only (filter "none").
  - `incorporateDependenciesAndVulnerabilities` boolean: Whether the referenced project's dependencies and vulnerabilities are included in the referencing project. Defaults to false.
  - `rationale` string: Reason recorded in the audit log

## Response `200`

Successful response

- object
  - `status` 'created' | 'already_exists', required: already_exists: the reference was there before this call and was left unchanged
  - `reference` object, required
    - `projectId` string, required
    - `referencedProjectId` string, required
    - `referenceableItemsFilter` string, nullable, required
    - `incorporatedItemsFilter` string, nullable, required
    - `incorporateDependenciesAndVulnerabilities` boolean, required

## Other responses

- `400`: Invalid input data
- `401`: Authorization not provided
- `403`: Insufficient access
- `500`: Internal server error

---

[API](https://skmtc.dev/ketryx/apis/ketryx-api.md) - [All operations](https://skmtc.dev/ketryx/apis/ketryx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ketryx/apis/ketryx-api/revisions/a2a484dc35ca?raw)