Projects

A project is an application workspace. It combines:

• durable model instructions;
• a hidden project-owned knowledge store for files and websites;
• references to existing shared datasets;
• user, role, and team permissions.

Use a project when the same instructions and knowledge should be reused across many chat requests or conversations.

Create a project

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/projects" -d '{
  "name":"Support assistant",
  "instructions":"Answer from approved support material. Say when evidence is missing.",
  "owner":"private"
}'

owner is private by default or org for an organization-shared project.

Add project knowledge

Upload private project material:

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -X POST "$BASE_URL/v1/projects/$PROJECT_ID/files" \
  -F "file=@support-playbook.pdf"

Or reference an existing dataset without copying it:

PUT /v1/projects/{project_id}/datasets/{dataset_id}

The caller must be authorized for both resources. Dataset references stay live: changes to the source dataset are visible to the project after ingestion.

Project file, website, re-ingestion, run-history, and schedule routes mirror the dataset routes under /v1/projects/{id}/....

Use the project in chat

{
  "model": "auto",
  "messages": [
    {"role": "user", "content": "How do I restore a deleted workspace?"}
  ],
  "project_id": "<project-id>",
  "agent_mode": "knowledge",
  "stream": false
}

Project instructions are added through the governed prompt assembly path. Project datasets are resolved from the hidden store and authorized references.

project_id and dataset_ids are mutually exclusive. Attach ad hoc datasets directly or use the reusable project, not both.

Share a project

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/projects/$PROJECT_ID/grants" -d '{
  "principal_type":"team",
  "principal_id":"<team-id>",
  "permission":"write"
}'

The permission ladder is read, write, then admin. Team principals must exist inside the same organization.

Connect a conversation

Create a stateful conversation with the project:

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/conversations" -d "{
  \"title\":\"Case 1842\",
  \"project_id\":\"$PROJECT_ID\"
}"

Subsequent requests use conversation_id; the server resolves the associated project and assembles its instructions and authorized context.

Delete

DELETE /v1/projects/{id} is asynchronous. It removes the hidden knowledge store and, when configured, project memory before hard-deleting the row. A failed backing-store purge retries and blocks the final deletion.