Prolific projects API

openapi: 3.1.0
info:
  title: API Reference aiTaskBuilder projects API
  version: 1.0.0
servers:
- url: https://api.prolific.com
  description: Production
tags:
- name: projects
paths:
  /api/v1/workspaces/{workspace_id}/projects/:
    get:
      operationId: get-projects
      summary: Get all projects in a workspace
      description: Gets a list of all the projects within the workspace.
      tags:
      - projects
      parameters:
      - name: workspace_id
        in: path
        description: Workspace id
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.


          Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


          If your token is leaked, delete it and create a new one directly in the app.


          In your requests add `Authorization` header with the value `Token <your token>`.'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectShortListResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-project
      summary: Create a project
      description: 'Creates a new project within the workspace.

        When this project is created, it adds the user as a Project Editor.

        Set `type` to `PUBLIC` to create a public project.'
      tags:
      - projects
      parameters:
      - name: workspace_id
        in: path
        description: Workspace id
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.


          Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


          If your token is leaked, delete it and create a new one directly in the app.


          In your requests add `Authorization` header with the value `Token <your token>`.'
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Successfully created project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProject'
  /api/v1/projects/{project_id}/:
    get:
      operationId: get-project
      summary: Get project
      description: Gets a project's details
      tags:
      - projects
      parameters:
      - name: project_id
        in: path
        description: Project id
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.


          Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


          If your token is leaked, delete it and create a new one directly in the app.


          In your requests add `Authorization` header with the value `Token <your token>`.'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: update-project
      summary: Update a project
      description: 'Update a project''s details.

        Public projects support partial updates to `public_details`.

        Once a public project has published studies, `public_details.title` can no longer be changed.'
      tags:
      - projects
      parameters:
      - name: project_id
        in: path
        description: Project id
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.


          Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


          If your token is leaked, delete it and create a new one directly in the app.


          In your requests add `Authorization` header with the value `Token <your token>`.'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Updated project redirect link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProject'
components:
  schemas:
    ProjectLongitudinal:
      type: object
      properties:
        config:
          oneOf:
          - $ref: '#/components/schemas/LongitudinalConfig'
          - type: 'null'
        retention:
          $ref: '#/components/schemas/ProjectLongitudinalRetention'
          description: Computed retention projections and actuals, keyed by wave study id.
      description: Only present when `is_longitudinal` is true.
      title: ProjectLongitudinal
    ErrorDetail:
      type: object
      properties:
        status:
          type: integer
          description: Status code as in the http standards
        error_code:
          type: integer
          description: Internal error code
        title:
          type: string
          description: Error title
        detail:
          $ref: '#/components/schemas/ErrorDetailDetail'
          description: Error detail
        additional_information:
          type: string
          description: Optional extra information
        traceback:
          type: string
          description: Optional debug information
        interactive:
          type: boolean
      required:
      - status
      - error_code
      - title
      - detail
      title: ErrorDetail
    Project:
      type: object
      properties:
        id:
          type: string
          description: Project id. It is created by Prolific.
        title:
          type: string
          description: Name of project
        description:
          type: string
          description: What is this project used for
        owner:
          type: string
          description: User id of the creator of the project. It is created by Prolific.
        type:
          $ref: '#/components/schemas/ProjectType'
        public_details:
          oneOf:
          - $ref: '#/components/schemas/PublicDetails'
          - type: 'null'
          description: Public metadata for `PUBLIC` projects. `null` for `PRIVATE` projects.
        users:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceUser'
          description: Data for all users who have access to this project
        workspace:
          type: string
          description: Id of the workspace this project is in. This is created by Prolific.
        naivety_distribution_rate:
          type:
          - number
          - 'null'
          format: double
          description: The rate at which the studies within this project are distributed.
        is_longitudinal:
          type: boolean
          description: Whether this is a longitudinal (multi-wave) project.
        longitudinal:
          oneOf:
          - $ref: '#/components/schemas/ProjectLongitudinal'
          - type: 'null'
          description: Only present when `is_longitudinal` is true.
      required:
      - id
      - title
      - type
      title: Project
    ProjectLongitudinalRetention:
      type: object
      properties: {}
      description: Computed retention projections and actuals, keyed by wave study id.
      title: ProjectLongitudinalRetention
    RangeFilterWeightings:
      type: object
      properties:
        selected_range:
          $ref: '#/components/schemas/RangeFilterWeightingsSelectedRange'
        weighting:
          type: number
          format: double
      required:
      - selected_range
      - weighting
      title: RangeFilterWeightings
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
      - error
      title: Error
    CompositeFilterFilterId:
      type: string
      enum:
      - and
      - or
      description: Composite filter group operator. Use `and` when every child filter must match, or `or` when at least one child filter must match.
      title: CompositeFilterFilterId
    ProjectShortListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ProjectShort'
          description: List of all projects for a user
      required:
      - results
      title: ProjectShortListResponse
    RangeFilterSelectedRangeUpper:
      oneOf:
      - type: integer
      - type: string
      - type: number
        format: double
      description: Your selected upper bound for the range.
      title: RangeFilterSelectedRangeUpper
    UpdateProject:
      type: object
      properties:
        title:
          type: string
          description: Name of project
        description:
          type: string
          description: What is this project used for
        owner:
          type: string
          description: User id of the creator of the project.
        position:
          type: integer
          description: Position of the project within a workspace.
        hidden:
          type: boolean
          description: Whether the project is hidden in workspace listings.
        type:
          $ref: '#/components/schemas/ProjectType'
        public_details:
          $ref: '#/components/schemas/PublicDetails'
          description: Public metadata for `PUBLIC` projects. Omit to leave unchanged.
        is_sequential:
          type: boolean
          description: Whether the project is configured as sequential.
      description: Partial update payload for a project. All fields are optional.
      title: UpdateProject
    WorkspaceUser:
      type: object
      properties:
        id:
          type: string
          description: Id of user
        name:
          type: string
          description: Name of user
        email:
          type: string
          description: email of user
        roles:
          type: array
          items:
            type: string
          description: User roles in workspace
      required:
      - id
      title: WorkspaceUser
    ErrorDetailDetail:
      oneOf:
      - type: string
      - type: array
        items:
          type: string
      - $ref: '#/components/schemas/ErrorDetailDetail2'
      description: Error detail
      title: ErrorDetailDetail
    RangeFilterWeightingsSelectedRangeLower:
      oneOf:
      - type: integer
      - type: string
      - type: number
        format: double
      title: RangeFilterWeightingsSelectedRangeLower
    CompositeFilter:
      type: object
      properties:
        filter_id:
          $ref: '#/components/schemas/CompositeFilterFilterId'
          description: Composite filter group operator. Use `and` when every child filter must match, or `or` when at least one child filter must match.
        selected_filters:
          type: array
          items:
            $ref: '#/components/schemas/CompositeFilterSelectedFiltersItems'
          description: Child filters in this group. Children can be select filters, range filters, or supported nested composite groups.
      required:
      - filter_id
      - selected_filters
      title: CompositeFilter
    PublicProjectStatus:
      type: string
      enum:
      - ENABLED
      - DISABLED
      description: Participant-facing publication status for a public project.
      title: PublicProjectStatus
    CreateProjectLongitudinal:
      type: object
      properties:
        config:
          $ref: '#/components/schemas/LongitudinalConfig'
      description: 'Longitudinal configuration. Only used when `is_longitudinal` is true.

        `waves` may not be set at creation — add studies via

        `POST /api/v1/projects/{project_id}/studies/` after creation.'
      title: CreateProjectLongitudinal
    RangeFilterSelectedRange:
      type: object
      properties:
        lower:
          $ref: '#/components/schemas/RangeFilterSelectedRangeLower'
          description: Your selected lower bound for the range.
        upper:
          $ref: '#/components/schemas/RangeFilterSelectedRangeUpper'
          description: Your selected upper bound for the range.
      description: 'This schema applies for filters of the `range` type, as defined in the [filter list response](\#tag/Filters/paths/~1api~1v1~1filters~1/get).


        A dictionary with two possible objects, ''lower'' and ''upper''. At least one must be present and a non-null value.


        The expected data type for these values is defined by the `range` filter''s `data_type` (see response linked above).


        If the data_type is a date, string format should be a parseable ISO8601 date string. Date values should be provided as a string in ISO 8601 format.


        Leaving a value as null will result in that bound being set to the lowest or highest possible value, depending on whether it is the upper or lower bound.'
      title: RangeFilterSelectedRange
    CompositeFilterSelectedFiltersItems:
      oneOf:
      - $ref: '#/components/schemas/SelectFilter'
      - $ref: '#/components/schemas/RangeFilter'
      - $ref: '#/components/schemas/CompositeFilter'
      title: CompositeFilterSelectedFiltersItems
    RangeFilterWeightingsSelectedRangeUpper:
      oneOf:
      - type: integer
      - type: string
      - type: number
        format: double
      title: RangeFilterWeightingsSelectedRangeUpper
    ProjectShort:
      type: object
      properties:
        id:
          type: string
          description: Project id. It is created by Prolific.
        title:
          type: string
          description: Name of project
        description:
          type: string
          description: What is this project used for
        owner:
          type: string
          description: User id of the creator of the project. It is created by Prolific.
        type:
          $ref: '#/components/schemas/ProjectType'
        public_details:
          oneOf:
          - $ref: '#/components/schemas/PublicDetails'
          - type: 'null'
          description: Public metadata for `PUBLIC` projects. `null` for `PRIVATE` projects.
        users:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceUser'
          description: Data for all users who have access to this project
        naivety_distribution_rate:
          type:
          - number
          - 'null'
          format: double
          description: The rate at which the studies within this project are distributed.
      required:
      - id
      - title
      - type
      title: ProjectShort
    SelectFilter:
      type: object
      properties:
        filter_id:
          type: string
          description: ID of the "select" type filter.
        selected_values:
          type: array
          items:
            type: string
          description: 'This schema applies for filters of the `select` type, as defined in the [filter list response](\#tag/Filters/paths/~1api~1v1~1filters~1/get).


            Array of IDs matching the response IDs, from the `select` filter''s `choices` (see response linked above).


            String format should match the `data_type` of the `select` filter''s `choices` (see response linked above).'
        weightings:
          type: object
          additionalProperties:
            type: number
            format: double
          description: 'Ratios to control the distribution of participants across the selected values.


            Integer percentages, floats, and exact quantities are valid inputs.'
      required:
      - filter_id
      - selected_values
      title: SelectFilter
    CreateProject:
      type: object
      properties:
        title:
          type: string
          description: Name of project
        description:
          type: string
          description: What is this project used for
        type:
          $ref: '#/components/schemas/ProjectType'
          default: PRIVATE
          description: 'Project visibility type.

            Set to `PUBLIC` to enable participant-facing public project metadata.'
        public_details:
          oneOf:
          - $ref: '#/components/schemas/PublicDetails'
          - type: 'null'
          description: 'Public metadata exposed for `PUBLIC` projects.

            Omit for `PRIVATE` projects.

            When creating a public project, `status` defaults to `ENABLED`.'
        naivety_distribution_rate:
          type:
          - number
          - 'null'
          format: double
          description: 'Control the balance between speed of your studies and the naivety of the participants.


            If not defined, by default Prolific calculates the best rate for most studies

            taking into account the `filters` and the `total_available_places` needed for this study.


            Use 0 if your priority is speed. When this property is set to 0 all eligible participants will have access

            to your study at the same time, without any prioritization.


            You can also set this at a workspace and study level.'
        is_longitudinal:
          type: boolean
          default: false
          description: Whether this is a longitudinal (multi-wave) project.
        longitudinal:
          oneOf:
          - $ref: '#/components/schemas/CreateProjectLongitudinal'
          - type: 'null'
          description: 'Longitudinal configuration. Only used when `is_longitudinal` is true.

            `waves` may not be set at creation — add studies via

            `POST /api/v1/projects/{project_id}/studies/` after creation.'
      required:
      - title
      title: CreateProject
    LongitudinalConfigFiltersItems:
      oneOf:
      - $ref: '#/components/schemas/SelectFilter'
      - $ref: '#/components/schemas/RangeFilter'
      - $ref: '#/components/schemas/CompositeFilter'
      title: LongitudinalConfigFiltersItems
    ProjectType:
      type: string
      enum:
      - PRIVATE
      - PUBLIC
      description: Project visibility type.
      title: ProjectType
    RangeFilterSelectedRangeLower:
      oneOf:
      - type: integer
      - type: string
      - type: number
        format: double
      description: Your selected lower bound for the range.
      title: RangeFilterSelectedRangeLower
    LongitudinalConfig:
      type: object
      properties:
        target_completions:
          type: integer
          description: Target number of completions for the final wave.
        retention_rate:
          type: number
          format: double
          description: Expected retention rate between waves.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/LongitudinalConfigFiltersItems'
          description: 'Recruitment filters applied to participants entering the first wave.

            Uses the same filter shapes as study creation.'
      required:
      - target_completions
      - retention_rate
      title: LongitudinalConfig
    RangeFilterWeightingsSelectedRange:
      type: object
      properties:
        lower:
          $ref: '#/components/schemas/RangeFilterWeightingsSelectedRangeLower'
        upper:
          $ref: '#/components/schemas/RangeFilterWeightingsSelectedRangeUpper'
      title: RangeFilterWeightingsSelectedRange
    PublicDetails:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/PublicProjectStatus'
          description: Status of the public project metadata. Defaults to `ENABLED`.
        title:
          type: string
          description: Participant-facing title for the public project.
        short_description:
          type: string
          description: Short participant-facing summary shown to participants for the public project.
        description:
          type: string
          description: Additional participant-facing information shown to participants for the public project.
      title: PublicDetails
    RangeFilter:
      type: object
      properties:
        filter_id:
          type: string
          description: ID of the "range" type filter.
        selected_range:
          $ref: '#/components/schemas/RangeFilterSelectedRange'
          description: 'This schema applies for filters of the `range` type, as defined in the [filter list response](\#tag/Filters/paths/~1api~1v1~1filters~1/get).


            A dictionary with two possible objects, ''lower'' and ''upper''. At least one must be present and a non-null value.


            The expected data type for these values is defined by the `range` filter''s `data_type` (see response linked above).


            If the data_type is a date, string format should be a parseable ISO8601 date string. Date values should be provided as a string in ISO 8601 format.


            Leaving a value as null will result in that bound being set to the lowest or highest possible value, depending on whether it is the upper or lower bound.'
        weightings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RangeFilterWeightings'
          description: 'Ratios to control the distribution of participants across the selected values.


            Integers and exact quantities are valid inputs.'
      required:
      - filter_id
      - selected_range
      title: RangeFilter
    ErrorDetailDetail2:
      type: object
      properties:
        any_field:
          type: array
          items:
            type: string
          description: Name of the field with a validation error and as a value an array with the error descriptions
      description: All fields with validation errors
      title: ErrorDetailDetail2
  securitySchemes:
    token:
      type: apiKey
      in: header
      name: Authorization
      description: 'The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.


        Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


        If your token is leaked, delete it and create a new one directly in the app.


        In your requests add `Authorization` header with the value `Token <your token>`.'