List, Retrieve, Update, Create Project and Project Forms

Where:

  • pk - is the project id
  • formid - is the form id
  • owner - is the username for the user or organization of the project

Register a new Project

POST /api/v1/projects

Example

  {
      "url": "https://kobo.humanitarianresponse.info/api/v1/projects/1",
      "owner": "https://kobo.humanitarianresponse.info/api/v1/users/ona",
      "name": "project 1",
      "date_created": "2013-07-24T13:37:39Z",
      "date_modified": "2013-07-24T13:37:39Z"
  }

List of Projects

GET /api/v1/projects

Example

  curl -X GET https://kobo.humanitarianresponse.info/api/v1/projects

Response

  [
      {
          "url": "https://kobo.humanitarianresponse.info/api/v1/projects/1",
          "owner": "https://kobo.humanitarianresponse.info/api/v1/users/ona",
          "name": "project 1",
          "date_created": "2013-07-24T13:37:39Z",
          "date_modified": "2013-07-24T13:37:39Z"
      },
      {
          "url": "https://kobo.humanitarianresponse.info/api/v1/projects/4",
          "owner": "https://kobo.humanitarianresponse.info/api/v1/users/ona",
          "name": "project 2",
          "date_created": "2013-07-24T13:59:10Z",
          "date_modified": "2013-07-24T13:59:10Z"
      }, ...
  ]

List of Projects filter by owner/organization

GET /api/v1/projects?owner=owner_username

Example

  curl -X GET https://kobo.humanitarianresponse.info/api/v1/projects?owner=ona

Retrieve Project Information

GET /api/v1/projects/{pk}

Example

  curl -X GET https://kobo.humanitarianresponse.info/api/v1/projects/1

Response

  {
      "url": "https://kobo.humanitarianresponse.info/api/v1/projects/1",
      "owner": "https://kobo.humanitarianresponse.info/api/v1/users/ona",
      "name": "project 1",
      "date_created": "2013-07-24T13:37:39Z",
      "date_modified": "2013-07-24T13:37:39Z"
  }

Update Project Information

PUT /api/v1/projects/{pk} or PATCH /api/v1/projects/{pk}

Example

   curl -X PATCH -d 'metadata={"description": "Lorem ipsum","location": "Nakuru, Kenya","category": "water"}' https://kobo.humanitarianresponse.info/api/v1/projects/1

Response

  {
      "url": "https://kobo.humanitarianresponse.info/api/v1/projects/1",
      "owner": "https://kobo.humanitarianresponse.info/api/v1/users/ona",
      "name": "project 1",
      "metadata": {
                   "description": "Lorem ipsum",
                   "location": "Nakuru, Kenya",
                   "category": "water"
                   }
      "date_created": "2013-07-24T13:37:39Z",
      "date_modified": "2013-07-24T13:37:39Z"
  }

Share a project with a specific user

You can share a project with a specific user by POST a payload with

  • username of the user you want to share the form with and
  • role you want the user to have on the project. Available roles are readonly, dataentry, editor, manager.
POST /api/v1/projects/{pk}/share

Example

  curl -X POST -d username=alice -d role=readonly https://kobo.humanitarianresponse.info/api/v1/projects/1/share

Response

   HTTP 204 NO CONTENT

Send an email to users on project share

An email is only sent when the email_msg request variable is present.

POST /api/v1/projects/{pk}/share

Example

  curl -X POST -d username=alice -d role=readonly -d email_msg=I have shared the project with you https://kobo.humanitarianresponse.info/api/v1/projects/1/share

Response

   HTTP 204 NO CONTENT

Remove a user from a project

You can remove a specific user from a project using POST with payload:

  • username of the user you want to remove
  • role the user has on the project
  • remove set remove to True

Example

  curl -X POST -d "username=alice" -d "role=readonly"  -d "remove=True" http://localhost:8000/api/v1/projects/1/share

Response

   HTTP 204 NO CONTENT

Assign a form to a project

To [re]assign an existing form to a project you need to POST a payload of formid=FORMID to the endpoint below.

POST /api/v1/projects/{pk}/forms

Example

  curl -X POST -d '{"formid": 28058}' https://kobo.humanitarianresponse.info/api/v1/projects/1/forms -H "Content-Type: application/json"

Response

  {
      "url": "https://kobo.humanitarianresponse.info/api/v1/forms/28058",
      "formid": 28058,
      "uuid": "853196d7d0a74bca9ecfadbf7e2f5c1f",
      "id_string": "Birds",
      "sms_id_string": "Birds",
      "title": "Birds",
      "allows_sms": false,
      "bamboo_dataset": "",
      "description": "",
      "downloadable": true,
      "encrypted": false,
      "owner": "ona",
      "public": false,
      "public_data": false,
      "date_created": "2013-07-25T14:14:22.892Z",
      "date_modified": "2013-07-25T14:14:22.892Z"
  }

Upload XLSForm to a project

POST /api/v1/projects/{pk}/forms

Example

  curl -X POST -F xls_file=@/path/to/form.xls https://kobo.humanitarianresponse.info/api/v1/projects/1/forms

Response

  {
      "url": "https://kobo.humanitarianresponse.info/api/v1/forms/28058",
      "formid": 28058,
      "uuid": "853196d7d0a74bca9ecfadbf7e2f5c1f",
      "id_string": "Birds",
      "sms_id_string": "Birds",
      "title": "Birds",
      "allows_sms": false,
      "bamboo_dataset": "",
      "description": "",
      "downloadable": true,
      "encrypted": false,
      "owner": "ona",
      "public": false,
      "public_data": false,
      "date_created": "2013-07-25T14:14:22.892Z",
      "date_modified": "2013-07-25T14:14:22.892Z"
  }

Get forms for a project

GET /api/v1/projects/{pk}/forms

Example

  curl -X GET https://kobo.humanitarianresponse.info/api/v1/projects/1/forms

Response

  [
      {
         "url": "https://kobo.humanitarianresponse.info/api/v1/forms/28058",
          "formid": 28058,
          "uuid": "853196d7d0a74bca9ecfadbf7e2f5c1f",
          "id_string": "Birds",
          "sms_id_string": "Birds",
          "title": "Birds",
          "allows_sms": false,
          "bamboo_dataset": "",
          "description": "",
          "downloadable": true,
          "encrypted": false,
          "owner": "ona",
          "public": false,
          "public_data": false,
          "date_created": "2013-07-25T14:14:22.892Z",
          "date_modified": "2013-07-25T14:14:22.892Z",
          "tags": [],
          "users": [
              {
                  "role": "owner",
                  "user": "alice",
                  "permissions": ["report_xform", ...]
              },
              ...
          ]
      },
      ...
  ]

Get list of projects with specific tag(s)

Use the tags query parameter to filter the list of projects, tags should be a comma separated list of tags.

GET /api/v1/projects?tags=tag1,tag2

List projects tagged smart or brand new or both.

Request

  curl -X GET https://kobo.humanitarianresponse.info/api/v1/projects?tag=smart,brand+new

Response HTTP 200 OK

  [
      {
          "url": "https://kobo.humanitarianresponse.info/api/v1/projects/1",
          "owner": "https://kobo.humanitarianresponse.info/api/v1/users/ona",
          "name": "project 1",
          "date_created": "2013-07-24T13:37:39Z",
          "date_modified": "2013-07-24T13:37:39Z"
      },
      ...
  ]

Get list of Tags for a specific Project

GET /api/v1/project/{pk}/labels

Request

  curl -X GET https://kobo.humanitarianresponse.info/api/v1/projects/28058/labels

Response

  ["old", "smart", "clean house"]

Tag a Project

A POST payload of parameter tags with a comma separated list of tags.

Examples

  • animal fruit denim - space delimited, no commas
  • animal, fruit denim - comma delimited
POST /api/v1/projects/{pk}/labels

Payload

{"tags": "tag1, tag2"}

Remove a tag from a Project

DELETE /api/v1/projects/{pk}/labels/tag_name

Request

  curl -X DELETE https://kobo.humanitarianresponse.info/api/v1/projects/28058/labels/tag1

or to delete the tag "hello world"

  curl -X DELETE https://kobo.humanitarianresponse.info/api/v1/projects/28058/labels/hello%20world

Response

   HTTP 200 OK

Add a star to a project

POST /api/v1/projects/{pk}/star

Remove a star to a project

DELETE /api/v1/projects/{pk}/star

Get user profiles that have starred a project

GET /api/v1/projects/{pk}/star

GET /api/v1/projects
HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

[
    {
        "url": "https://kc.humanitarianresponse.info/api/v1/projects/1004",
        "projectid": 1004,
        "owner": "https://kc.humanitarianresponse.info/api/v1/users/rpenaranda",
        "created_by": "https://kc.humanitarianresponse.info/api/v1/users/rpenaranda",
        "metadata": null,
        "starred": false,
        "users": [
            {
                "role": "owner",
                "user": "rpenaranda",
                "permissions": [
                    "add_project",
                    "add_xform",
                    "change_project",
                    "delete_project",
                    "transfer_project",
                    "view_project"
                ]
            },
            {
                "role": "readonly",
                "user": "raulpenaranda",
                "permissions": [
                    "view_project"
                ]
            }
        ],
        "forms": [],
        "public": true,
        "tags": [],
        "num_datasets": 0,
        "last_submission_date": [],
        "name": "Agua",
        "shared": true,
        "date_created": "2020-04-25T16:47:39.373164Z",
        "date_modified": "2020-04-26T20:55:29.620933Z"
    },
    {
        "url": "https://kc.humanitarianresponse.info/api/v1/projects/1008",
        "projectid": 1008,
        "owner": "https://kc.humanitarianresponse.info/api/v1/users/jabad",
        "created_by": "https://kc.humanitarianresponse.info/api/v1/users/jabad",
        "metadata": {
            "category": "water",
            "description": "Lorem ipsum from Postman",
            "location": "Madrid, Spain"
        },
        "starred": false,
        "users": [
            {
                "role": "owner",
                "user": "jabad",
                "permissions": [
                    "add_project",
                    "add_xform",
                    "change_project",
                    "delete_project",
                    "transfer_project",
                    "view_project"
                ]
            }
        ],
        "forms": [
            {
                "name": "My OCHA Project from Web UI",
                "id": 531884
            }
        ],
        "public": true,
        "tags": [],
        "num_datasets": 1,
        "last_submission_date": "2020-06-07T10:21:02Z",
        "name": "Test Project from v1 API UPDATED",
        "shared": true,
        "date_created": "2020-05-24T22:50:13.953329Z",
        "date_modified": "2020-05-31T11:39:10.658920Z"
    },
    {
        "url": "https://kc.humanitarianresponse.info/api/v1/projects/1009",
        "projectid": 1009,
        "owner": "https://kc.humanitarianresponse.info/api/v1/users/jabad",
        "created_by": "https://kc.humanitarianresponse.info/api/v1/users/jabad",
        "metadata": null,
        "starred": false,
        "users": [
            {
                "role": "owner",
                "user": "jabad",
                "permissions": [
                    "add_project",
                    "add_xform",
                    "change_project",
                    "delete_project",
                    "transfer_project",
                    "view_project"
                ]
            }
        ],
        "forms": [
            {
                "name": "Copy_of_my_xlsform",
                "id": 554918
            }
        ],
        "public": true,
        "tags": [],
        "num_datasets": 1,
        "last_submission_date": "2020-06-07T10:41:39.333Z",
        "name": "Project desde la API UPDATED",
        "shared": true,
        "date_created": "2020-06-05T20:00:00.099903Z",
        "date_modified": "2020-06-05T20:01:29.110317Z"
    }
]