<commit_before>{% extends 'direct-sharing/layout.html' %}

{% block content %}
<h3>API data access</h3>

<p>
  Once Members are sharing data with you, you'll be able to immediately access
  that data via our Private Data API. Your project will have a master token
  that you can use to retrieve data from Members, associated with a
  project-specific user ID code.
</p>

<p>
  To retrieve data:
</p>
<ol>
  <li><p>
    <b>Find your "master access token".</b>
    Go to <a href="{% url 'direct-sharing:manage-projects' %}">your project
    management page</a> and click on your project's name. The master access
    token should be listed in your project's details.
  </p></li>
  <li><p>
    <b>Keep the "master access token" safe!</b> This token is used to authorize
    access to ALL private data shared with your project. If you ever believe
    the security of this token may have been compromised, contact us at
    <EMAIL> and we'll reset it to a new value.
  </p></li>
  <li>
    <p>
      <b>Use the master access token to access project data.</b>
      To access private data shared with your project, send a secure GET request
      (using 'https') to the following URL with the 'access_token' parameter set
      to your project's "master access token":
    </p>
    <p><code>
      https://www.openhumans.org/api/direct-sharing/project/members/?access_token=&lt;MASTER_ACCESS_TOKEN&gt;
    </code></p>
    <p>
      This returns JSON-formatted data that can be used to programmatically
      access and retrieve data and files for your project members.
    </p>
  </li>
</ol>

<h4>OAuth2 project member endpoint</h4>

<p>
  Projects interacting with OAuth2 authorization have an additional API
  endpoint. This OAuth2-specific API allows OAuth2 projects to retrieve
  the project member ID corresponding to the token their OAuth2 process
  generates. This API also returns other data associated with the
  project member, and can be used for "social login" (i.e. allowing users
  to log in via their Open Humans account, instead of via a password on your
  website or app).
</p>

<p>
  To access project member ID and privately shared project member data for
  a specific user, send a secure GET request (using 'https') to the following
  URL with the 'access_token' parameter set to the user's OAuth2 "access token":
</p>
<p><code>
  https://www.openhumans.org/api/direct-sharing/project/exchange-member/?access_token=&lt;USER_ACCESS_TOKEN&gt;
</code></p>
<p>
  This returns JSON-formatted data that can be used to programmatically
  access and retrieve data and files for this specific project member.
</p>
{% endblock %}<commit_msg>📝 add messaging endpoint documentation<commit_after>{% extends 'direct-sharing/layout.html' %}

{% block content %}
<h3>API data access</h3>

<p>
  Once Members are sharing data with you, you'll be able to immediately access
  that data via our Private Data API. Your project will have a master token
  that you can use to retrieve data from Members, associated with a
  project-specific user ID code.
</p>

<p>
  To retrieve data:
</p>
<ol>
  <li><p>
    <b>Find your "master access token".</b>
    Go to <a href="{% url 'direct-sharing:manage-projects' %}">your project
    management page</a> and click on your project's name. The master access
    token should be listed in your project's details.
  </p></li>
  <li><p>
    <b>Keep the "master access token" safe!</b> This token is used to authorize
    access to ALL private data shared with your project. If you ever believe
    the security of this token may have been compromised, contact us at
    <EMAIL> and we'll reset it to a new value.
  </p></li>
  <li>
    <p>
      <b>Use the master access token to access project data.</b>
      To access private data shared with your project, send a secure GET request
      (using 'https') to the following URL with the 'access_token' parameter set
      to your project's "master access token":
    </p>
    <p><code>
      https://www.openhumans.org/api/direct-sharing/project/members/?access_token=&lt;MASTER_ACCESS_TOKEN&gt;
    </code></p>
    <p>
      This returns JSON-formatted data that can be used to programmatically
      access and retrieve data and files for your project members.
    </p>
  </li>
</ol>

<h4>OAuth2 project member endpoint</h4>

<p>
  Projects interacting with OAuth2 authorization have an additional API
  endpoint. This OAuth2-specific API allows OAuth2 projects to retrieve
  the project member ID corresponding to the token their OAuth2 process
  generates. This API also returns other data associated with the
  project member, and can be used for "social login" (i.e. allowing users
  to log in via their Open Humans account, instead of via a password on your
  website or app).
</p>

<p>
  To access project member ID and privately shared project member data for
  a specific user, send a secure GET request (using 'https') to the following
  URL with the 'access_token' parameter set to the user's OAuth2 "access token":
</p>
<p><code>
  https://www.openhumans.org/api/direct-sharing/project/exchange-member/?access_token=&lt;USER_ACCESS_TOKEN&gt;
</code></p>
<p>
  This returns JSON-formatted data that can be used to programmatically
  access and retrieve data and files for this specific project member.
</p>

<h4>Messaging endpoint</h4>

<p>
  You can use the messaging endpoint to send messages to all the members of
  your project or a specified subset.
</p>

<p>
  The endpoint takes these parameters as a JSON object:
</p>

<ul>
  <li><code>all_members</code>: If specified it must be <code>true</code> or
    <code>false</code>.</li>

  <li><code>project_member_ids</code>: An array of project member IDs to send
    messages to.</li>

  <li><code>message</code>: The text of the message to send. For details on
    what the message text can contain and how it appears to the end user please
    see the <a href="{% url 'direct-sharing:sending-messages' %}">messaging
    documentation</a>.</li>
</ul>

<p>
  You must either specify <code>true</code> for <code>all_members</code>
  <em>or</em> specify an array of <code>project_member_ids</code> but not both.
</p>

<p>
  The URL for the messaging endpoint is:
</p>

<p><code>
  https://www.openhumans.org/api/direct-sharing/project/message/?access_token=&lt;MASTER_ACCESS_TOKEN&gt;
</code></p>

<h5>Examples</h5>

<p>
  These two examples show sending a message to all members and to a specified
  array of project member IDs with the <a
  href="http://www.httpie.org/">httpie</a> tool:
</p>

<pre>
  TOKEN="&lt;MASTER_ACCESS_TOKEN&gt;"
  URL="https://www.openhumans.org/api/direct-sharing/project/message/?access_token=$TOKEN"

  http -v POST $URL all_members:=true message:='"example message text"'
  http -v POST $URL project_member_ids:='["12345678", "56781234"]' message:='"example message text"'
</pre>
{% endblock %}
{'fraction_non_alphanumeric': 0.1043060808844923, 'fraction_numerical': 0.005819028222286878, 'mean_word_length': 3.7381116471399034, 'pattern_counts': {'":': 4, '<': 147, '<?xml version=': 0, '>': 147, 'https://': 6, 'lorem ipsum': 0, 'www.': 7, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6539634', 'n_tokens_mistral': 2142, 'n_tokens_neox': 2050, 'n_words': 875}