> For the complete documentation index, see [llms.txt](https://docs.veedna.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veedna.com/lineaje-api/project-workflow.md).
# Project Workflow
Onboard a project from private source code and drive it through remediation: create a project → list projects until the scan is "Ready for review" → fetch the Gold Plan → apply the Gold Plan.
## Step 1a: Add private source configuration
> Add a configuration with a name and description. These APIs apply to the SCM types \`github\`, \`bitbucket\`, \`gitlab\`, and \`git\`. The returned \`configurationId\` is used to add the project (repository) in the next call.
```json
{"openapi":"3.0.3","info":{"title":"Lineaje API Documentation","version":"1.0.0"},"tags":[{"name":"Project Workflow","description":"Onboard a project from private source code and drive it through remediation: create a project → list projects until the scan is \"Ready for review\" → fetch the Gold Plan → apply the Gold Plan.\n"}],"servers":[{"url":"https://scm-service.v2.prod.veedna.com","description":"SCM / integrations service"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Short-lived access token from the login or renew-access-token endpoint."}},"schemas":{"ScmConfigurationSaveRequest":{"type":"object","required":["name","description","accessToken","connector"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"accessToken":{"type":"string","description":"SCM personal access token."},"connector":{"type":"string","description":"SCM type.","enum":["github","bitbucket","gitlab","git"]}}},"ScmConfigurationSaveResponse":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"$ref":"#/components/schemas/ScmConfigurationData"}}},"Status":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"integer"}}},"ScmConfigurationData":{"type":"object","properties":{"createdBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"configurationId":{"type":"integer"},"tenantId":{"type":"string"},"companyId":{"type":"string"},"userRoles":{"type":"string"},"configurationName":{"type":"string"},"configurationDescription":{"type":"string"},"connectorId":{"type":"string"},"secretKeyName":{"type":"string"}}}}},"paths":{"/integrations/scm/api/v1/github/configuration/save":{"post":{"tags":["Project Workflow"],"summary":"Step 1a: Add private source configuration","operationId":"saveScmConfiguration","description":"Add a configuration with a name and description. These APIs apply to the SCM types `github`, `bitbucket`, `gitlab`, and `git`. The returned `configurationId` is used to add the project (repository) in the next call.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScmConfigurationSaveRequest"}}}},"responses":{"201":{"description":"Configuration saved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScmConfigurationSaveResponse"}}}}}}}}}
```
## Step 1b: Add private source project (repository)
> Add a project (repository) using the \`configurationId\` from the configuration/save call. Supply either a branch (set \`branch: true\` with \`branchName\`) or a tag (set \`branch: false\` with \`tagName\`) per repository entry.
```json
{"openapi":"3.0.3","info":{"title":"Lineaje API Documentation","version":"1.0.0"},"tags":[{"name":"Project Workflow","description":"Onboard a project from private source code and drive it through remediation: create a project → list projects until the scan is \"Ready for review\" → fetch the Gold Plan → apply the Gold Plan.\n"}],"servers":[{"url":"https://scm-service.v2.prod.veedna.com","description":"SCM / integrations service"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Short-lived access token from the login or renew-access-token endpoint."}},"schemas":{"ScmRepositoryAddRequest":{"type":"object","required":["connector","configurationId","repositoryDtoList"],"properties":{"connector":{"type":"string","enum":["github","bitbucket","gitlab","git"]},"configurationId":{"type":"integer"},"repositoryDtoList":{"type":"array","items":{"$ref":"#/components/schemas/RepositoryDto"}}}},"RepositoryDto":{"type":"object","properties":{"repositoryName":{"type":"string"},"repositoryUri":{"type":"string"},"private":{"type":"boolean"},"projectName":{"type":"string"},"projectVersion":{"type":"string"},"branchName":{"type":"string"},"branch":{"type":"boolean","description":"true when onboarding a branch (with branchName); false when onboarding a tag (with tagName)."},"tagName":{"type":"string"}}},"ScmRepositoryAddResponse":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"allOf":[{"$ref":"#/components/schemas/ScmConfigurationData"},{"type":"object","properties":{"scmRepositoryEntities":{"type":"array","items":{"$ref":"#/components/schemas/ScmRepositoryEntity"}},"scmPublicRepositoryEntities":{"type":"array","items":{"type":"object"}}}}]}}},"Status":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"integer"}}},"ScmConfigurationData":{"type":"object","properties":{"createdBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"configurationId":{"type":"integer"},"tenantId":{"type":"string"},"companyId":{"type":"string"},"userRoles":{"type":"string"},"configurationName":{"type":"string"},"configurationDescription":{"type":"string"},"connectorId":{"type":"string"},"secretKeyName":{"type":"string"}}},"ScmRepositoryEntity":{"type":"object","properties":{"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"repositoryId":{"type":"integer"},"repository_name":{"type":"string"},"repository_uri":{"type":"string"},"branch_name":{"type":"string"},"is_private":{"type":"boolean"},"project_name":{"type":"string"},"project_version":{"type":"string"}}}}},"paths":{"/integrations/scm/api/v1/github/configuration/repository":{"post":{"tags":["Project Workflow"],"summary":"Step 1b: Add private source project (repository)","operationId":"addScmRepository","description":"Add a project (repository) using the `configurationId` from the configuration/save call. Supply either a branch (set `branch: true` with `branchName`) or a tag (set `branch: false` with `tagName`) per repository entry.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScmRepositoryAddRequest"}}}},"responses":{"201":{"description":"Repositories saved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScmRepositoryAddResponse"}}}}}}}}}
```
## Step 2: List projects
> List projects for the authenticated tenant. Match the project name and version you onboarded, and keep polling until \`"jobStatus": "Ready for review"\` appears for that project/version. The \`sbomId\` returned here is required as the \`sbom\_id\` input when fetching and applying the Gold Plan.
```json
{"openapi":"3.0.3","info":{"title":"Lineaje API Documentation","version":"1.0.0"},"tags":[{"name":"Project Workflow","description":"Onboard a project from private source code and drive it through remediation: create a project → list projects until the scan is \"Ready for review\" → fetch the Gold Plan → apply the Gold Plan.\n"}],"servers":[{"url":"https://scim-service.v2.prod.veedna.com","description":"SCIM service"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Short-lived access token from the login or renew-access-token endpoint."}},"schemas":{"ProjectListResponse":{"type":"object","properties":{"results":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}}},"total_count":{"type":"integer"},"current_page":{"type":"integer"},"total_pages":{"type":"integer"},"page_size":{"type":"integer"}}},"Project":{"type":"object","properties":{"projectName":{"type":"string"},"projectVersion":{"type":"string"},"orgName":{"type":"string"},"projectStatus":{"type":"string"},"generationType":{"type":"string"},"sbomJobs":{"type":"array","items":{"$ref":"#/components/schemas/SbomJob"}}}},"SbomJob":{"type":"object","properties":{"projectId":{"type":"integer"},"name":{"type":"string"},"version":{"type":"string"},"jobId":{"type":"integer"},"sbomId":{"type":"string"},"tenantId":{"type":"string"},"uniqueOrgId":{"type":"string"},"sbomType":{"type":"string"},"crawlerType":{"type":"string"},"jobStatus":{"type":"string"},"jobMessage":{"type":"string"},"projectGroup":{"type":"string","nullable":true},"userEmail":{"type":"string"},"orgName":{"type":"string"},"generationMethod":{"type":"string"},"generationType":{"type":"string"},"created_by":{"type":"string"},"modified_by":{"type":"string"},"created_date":{"type":"string"},"modified_date":{"type":"string"}}}}},"paths":{"/scim/api/v2/projects/":{"get":{"tags":["Project Workflow"],"summary":"Step 2: List projects","operationId":"listProjects","description":"List projects for the authenticated tenant. Match the project name and version you onboarded, and keep polling until `\"jobStatus\": \"Ready for review\"` appears for that project/version. The `sbomId` returned here is required as the `sbom_id` input when fetching and applying the Gold Plan.\n","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":0}},{"name":"size","in":"query","schema":{"type":"integer","default":2000}},{"name":"projectFilter","in":"query","allowEmptyValue":true,"schema":{"type":"string"}},{"name":"timestamp","in":"query","schema":{"type":"integer"}},{"name":"token","in":"header","required":false,"description":"Access token, also sent here in addition to the Authorization header.","schema":{"type":"string"}}],"responses":{"200":{"description":"Project list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectListResponse"}}}}}}}}}
```
## Steps 3 & 4: Fetch and apply the Gold Plan
> Issue an \`/explain\` call to the GPT (Lineaje AI) service. This single endpoint drives both fetching and applying the Gold Plan, distinguished by the request body (see the request examples):\
> \
> \*\*Fetch (Step 3).\*\* Send \`query: "Recommend a fix plan"\` with the \`sbom\_id\` and \`options\`. The first response returns a \`guid\` and \`"Request is Queued"\`. Poll the same endpoint with that \`guid\` (about every 20 seconds; it can take several minutes) until the plan is ready. The ready response contains \`meta\_data.plan\_details\` (with \`current\_purl\`, \`suggested\_purl\`, and a \`plan\_type\` of \`curated\`, \`rebuild\`, or \`premium\`), \`overall\_status\`, and — when \`include\_artifacts\`/\`include\_pr\_history\` are \`true\` — \`artifacts\` and \`pr\_history\`.\
> \
> \*\*Apply (Step 4).\*\* Send \`query: "Apply fix left plan"\` with the \`sbom\_id\` and a \`metadata.components\` array containing only the components to include in the PR (for example, exclude premium candidates). There is no need to wait for the response; the task runs AI agents and creates a PR after several minutes. Call the fetch step again later to read the new \`pr\_history\`.
```json
{"openapi":"3.0.3","info":{"title":"Lineaje API Documentation","version":"1.0.0"},"tags":[{"name":"Project Workflow","description":"Onboard a project from private source code and drive it through remediation: create a project → list projects until the scan is \"Ready for review\" → fetch the Gold Plan → apply the Gold Plan.\n"}],"servers":[{"url":"https://lineaje-gpt-service.v2.prod.veedna.com","description":"Lineaje GPT (AI) service"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Short-lived access token from the login or renew-access-token endpoint."}},"schemas":{"ExplainRequest":{"type":"object","required":["query","sbom_id"],"properties":{"query":{"type":"string","description":"\"Recommend a fix plan\" to fetch/poll; \"Apply fix left plan\" to apply."},"sbom_id":{"type":"string"},"options":{"type":"object","description":"Set both true to populate artifacts and pr_history in the ready response.","properties":{"include_artifacts":{"type":"boolean"},"include_pr_history":{"type":"boolean"}}},"guid":{"type":"string","description":"Include the guid returned by the first fetch call to poll for the result."},"metadata":{"type":"object","description":"Apply-plan payload — the components to include in the PR.","properties":{"components":{"type":"array","items":{"$ref":"#/components/schemas/PlanComponent"}}}}}},"PlanComponent":{"type":"object","description":"A component in a Gold Plan (used in plan_details and in the apply request).","properties":{"version":{"type":"string"},"type":{"type":"string","description":"Plan type for the component: curated, rebuild, or premium."},"patch_type":{"type":"string"},"status":{"type":"string"},"fix_version":{"type":"string"},"build_breaking_changes":{"type":"boolean"},"is_compatible":{"type":"boolean"},"vuln_fixed":{"type":"array","items":{"type":"string"}},"vuln_not_fixed":{"type":"array","items":{"type":"string"}},"vuln_fix_count":{"type":"object","properties":{"critical":{"type":"integer"},"high":{"type":"integer"},"medium":{"type":"integer"},"low":{"type":"integer"}}},"efforts":{"type":"string"},"summary":{"type":"string"},"current_purl":{"type":"string"},"suggested_purl":{"type":"string"}}},"ExplainResponse":{"type":"object","properties":{"response_time":{"type":"number"},"answer":{"type":"string","nullable":true},"graphql":{"nullable":true},"query_suggestions":{"nullable":true},"view_details":{"nullable":true},"meta_data":{"type":"object","nullable":true,"properties":{"plan_details":{"type":"array","items":{"$ref":"#/components/schemas/PlanComponent"}},"overall_status":{"type":"string"},"overall_plan_type":{"type":"string"},"pr_history":{"type":"array","items":{"$ref":"#/components/schemas/PrHistory"}},"artifacts":{"type":"array","items":{"type":"string"}}}},"metadata_v2":{"type":"object"},"task_ids":{"type":"array","items":{"type":"string"}},"column":{"nullable":true},"view_schema":{"nullable":true},"Greeting":{"nullable":true},"guid":{"type":"string","nullable":true},"message":{"type":"string","nullable":true},"workflow_id":{"type":"string","nullable":true},"error":{"type":"boolean"}}},"PrHistory":{"type":"object","properties":{"created":{"type":"string"},"status":{"type":"string"},"pr_link":{"type":"string"},"pr_number":{"type":"string"},"pr_title":{"type":"string"}}}}},"paths":{"/api/v1/explain":{"post":{"tags":["Project Workflow"],"summary":"Steps 3 & 4: Fetch and apply the Gold Plan","operationId":"explain","description":"Issue an `/explain` call to the GPT (Lineaje AI) service. This single endpoint drives both fetching and applying the Gold Plan, distinguished by the request body (see the request examples):\n\n**Fetch (Step 3).** Send `query: \"Recommend a fix plan\"` with the `sbom_id` and `options`. The first response returns a `guid` and `\"Request is Queued\"`. Poll the same endpoint with that `guid` (about every 20 seconds; it can take several minutes) until the plan is ready. The ready response contains `meta_data.plan_details` (with `current_purl`, `suggested_purl`, and a `plan_type` of `curated`, `rebuild`, or `premium`), `overall_status`, and — when `include_artifacts`/`include_pr_history` are `true` — `artifacts` and `pr_history`.\n\n**Apply (Step 4).** Send `query: \"Apply fix left plan\"` with the `sbom_id` and a `metadata.components` array containing only the components to include in the PR (for example, exclude premium candidates). There is no need to wait for the response; the task runs AI agents and creates a PR after several minutes. Call the fetch step again later to read the new `pr_history`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainRequest"}}}},"responses":{"200":{"description":"Queued, not-ready, or completed response. While queued or polling, `answer`/`meta_data` are null and `message` reflects status. When the plan is ready, `meta_data` is populated.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainResponse"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.veedna.com/lineaje-api/project-workflow.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.