Create a Project

Creates a new Marvin project that you can then use as project_id for File Import, Insight Import, or Survey Import.

Requirements#

• Scope: project:write (add it to your token request, e.g. scope=project:read project:write file:write)
• Team setting allow_manual_project_creation must be enabled — otherwise the API returns 403

See API Key Integration Guide for the full auth setup.

export BASE_URL="https://app.heymarvin.com"
export CLIENT_ID="cid-mrv_..."
export CLIENT_SECRET="sk-mrv_..."

TOKEN=$(curl -s -X POST "$BASE_URL/api/v1/oauth/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=project:read project:write file:write" \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")

What happens on create#

1. Project is created for the API key’s user
2. Sharing defaults come from the team unless you override project_share_preference
3. A default (empty) label template is created and attached to the project
4. Response returns { "id", "name" } — use id as project_id in initialize

POST /api/v1/developer/import/projects/create #

curl -s -X POST "$BASE_URL/api/v1/developer/import/projects/create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Customer Calls",
    "supported_languages": ["en-US"],
    "project_share_preference": 1
  }' | python3 -m json.tool

Response (201):

{
  "id": 44,
  "name": "Q3 Customer Calls"
}

Required fields#

Language & AI settings#

auto_ai_notes_payload shape:

{
  "skip_discussion_guide": false,
  "auto_apply_labels": false
}

The API stores this as an enabled auto-notes config (is_enabled: true, empty selected_guides). Pass the object to enable the feature; omit it to leave auto-notes off.

Sharing settings#

If you omit sharing fields, the new project inherits the team’s default share preference.

Share modes

shared_roles role IDs (used with preference 4):

Examples:

{ "name": "Private Drafts", "project_share_preference": 1 }

{
  "name": "Admin Review",
  "project_share_preference": 4,
  "shared_roles": [3]
}

{
  "name": "Team Editors",
  "project_share_preference": 4,
  "shared_roles": [0, 3, 4]
}

{ "name": "Company-wide Research", "project_share_preference": 2 }

Privacy / auto-PII settings#

These set the project’s default PII / privacy behavior for files imported into it.

Important: if you send any of the PII fields below and do not send auto_pii_enabled_at_project_level, the API automatically sets auto_pii_enabled_at_project_level = true so auto-PII runs on new files. To configure settings without enabling that pipeline, pass "auto_pii_enabled_at_project_level": false explicitly.

Typical combinations

• Transcript + audio redaction: redact_pii: true, optionally pii_redaction_category, pii_redaction_type: ["transcript", "audio"]
• Face blur: anonymize_video: "blur_faces"
• Stronger video privacy: anonymize_video: "blur_entire_video" and/or audio_modulation: true
• Hide speaker identities in UI: speaker_anonymization: "only_participants"

Full example:

{
  "name": "Compliance Interviews",
  "supported_languages": ["en-US"],
  "default_ai_language": "en-US",
  "disable_search_ask_ai": false,
  "project_share_preference": 2,
  "auto_ai_notes_payload": {
    "skip_discussion_guide": true,
    "auto_apply_labels": false
  },
  "redact_pii": true,
  "pii_redaction_type": ["transcript", "audio"],
  "anonymize_video": "blur_faces",
  "audio_modulation": true,
  "speaker_anonymization": "only_participants"
}

Errors#